Link: start Link: parent Link: First page in set (first) Link: Previous page (previous) Link: Next page (next) Link: Last page in set (last) Link: A plain text version of this page (alternate) Link: The XIST source of this page (alternate) Link: The Python module described in this page (alternate) XIST.xsc ======== XIST core classes ================= Home > Python software > ll.xist > xsc Text · XIST · Python Python softwarelist of projects * ll.xistAn extensible XML/HTML generator * ExamplesParsing/creating/modifying XML; Traversing XML trees * HowtoExplains parsing/generating XML files, XML transformations via XIST classes and other basic concepts. * SearchingHow to iterate through XIST trees * TransformationHow to transform XIST trees * Advanced topicsPool chaining, converter contexts, validation * MiscellaneousExplains various odds and ends of XIST * xscXIST core classes * nsPackage containing namespace modules * parseParsing XML * presentScreen output of XML trees * simsSimple schema validation * xfindTree iteration and filtering * cssCSS related functions * scriptsScripts for text conversion and creating XIST namespaces * HistoryChangeLog for XIST * InstallationHow to install and configure XIST * MigrationHow to update your code to new versions of XIST * Mailing listsHow to subscribe to the XIST mailing lists * ll.ul4cA templating language * ll.urlRFC 2396 compliant URLs * ll.makeObject oriented make replacement * ll.daemonForking daemon processes * ll.sisyphusWriting cron jobs with Python * ll.colorRGB color values and color model conversion * ll.miscMisc utility functions and classes * ll.orasqlUtilities for cx_Oracle * ll.nightshadeServe the output of Oracle functions/procedures with CherryPy * ll.scriptsScripts for UL4 template rendering and URL handling * AploraLogging Apache HTTP requests to an Oracle database * PycocoPython code coverage * DownloadLinks to Windows and Linux, source and binary distributions * Source codeAccess to the Mercurial repositories This module contains all the central XML tree classes, the namespace classes, exception and warning classes and a few helper classes and functions. def 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 ThreadLocalNodeHander(thread._local): ============================================ class build(object): ===================== A build object can be used as a with block handler to create a new XIST tree: with xsc.build(): with html.ul() as e: +html.li("gurk") +html.li("hurz") def __init__(self): ==================== def __enter__(self): ===================== def __exit__(self, type, value, traceback): ============================================ def enter(self, node): ======================= def exit(self): ================ def add(self, *args, **kwargs): ================================ class addattr(object): ======================= An addattr object can be used as a with block handler to modify an attribute of an element: with xsc.build(): with html.div() as e: with xsc.addattr("align"): +xsc.Text("right") def __init__(self, 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). def __enter__(self): ===================== def __exit__(self, type, value, traceback): ============================================ def add(self, *args): ====================== def add(*args, **kwargs): ========================== add appends items in args and sets attributes in kwargs in the currenly active node in the with stack. class Context(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. class Error(Exception): ======================== Base class for all XIST exceptions class Warning(UserWarning): ============================ Base class for all warning exceptions (i.e. those that won't result in a program termination.) class IllegalAttrValueWarning(Warning): ======================================== Warning that is issued when an attribute has an illegal value when parsing or publishing. def __init__(self, attr): ========================== def __str__(self): =================== class RequiredAttrMissingWarning(Warning): =========================================== Warning that is issued when a required attribute is missing during parsing or publishing. def __init__(self, attrs, reqattrs): ===================================== def __str__(self): =================== class IllegalPrefixError(Error, LookupError): ============================================== Exception that is raised when a namespace prefix is undefined. def __init__(self, prefix): ============================ def __str__(self): =================== class IllegalElementError(Error, LookupError): =============================================== Exception that is raised when an illegal element class is requested def __init__(self, name, xmlns, xml=False): ============================================ def __str__(self): =================== class IllegalProcInstError(Error, LookupError): ================================================ Exception that is raised when an illegal procinst class is requested def __init__(self, name, xml=False): ===================================== def __str__(self): =================== class IllegalEntityError(Error, LookupError): ============================================== Exception that is raised when an illegal entity class is requested def __init__(self, name, xml=False): ===================================== def __str__(self): =================== class IllegalCharRefError(Error, LookupError): =============================================== Exception that is raised when an illegal charref class is requested def __init__(self, name, xml=False): ===================================== def __str__(self): =================== class IllegalAttrError(Error, LookupError): ============================================ Exception that is raised when an illegal attribute is requested. def __init__(self, name, cls, xml=False): ========================================== def __str__(self): =================== class MultipleRootsError(Error): ================================= def __str__(self): =================== class ElementNestingError(Error): ================================== Exception that is raised when an element has an illegal nesting (e.g. ) def __init__(self, expectedelement, foundelement): =================================================== def __str__(self): =================== class FileNotFoundWarning(Warning): ==================================== Warning that is issued when a file can't be found. def __init__(self, message, filename, exc): ============================================ def __str__(self): =================== class IllegalObjectError(Error, TypeError): ============================================ Exception that is raised when an XIST constructor gets passed an unconvertable object. def __init__(self, object): ============================ def __str__(self): =================== class IllegalCommentContentWarning(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.) def __init__(self, comment): ============================= def __str__(self): =================== class IllegalProcInstFormatError(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.) def __init__(self, procinst): ============================== def __str__(self): =================== class ConverterState(object): ============================== def __init__(self, node, root, mode, stage, target, lang, makeaction, makeproject): ==================================================================================== class Converter(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. def __init__(self, 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. property node: ============== The root node for which conversion has been called. This is automatically set by the conv method of Node objects. def __get__(self): ------------------- def __set__(self, node): ------------------------- def __delete__(self): ---------------------- property root: ============== The root URL for the conversion. Resolving URLs during the conversion process should be done relative to root. def __get__(self): ------------------- def __set__(self, root): ------------------------- def __delete__(self): ---------------------- property mode: ============== The conversion mode. This corresponds directly to the mode in XSLT. The default is None. def __get__(self): ------------------- def __set__(self, mode): ------------------------- def __delete__(self): ---------------------- property stage: =============== If your conversion is done in multiple steps or stages you can use this property to specify in which stage the conversion process currently is. The default is "deliver". def __get__(self): ------------------- def __set__(self, stage): -------------------------- def __delete__(self): ---------------------- property target: ================ Specifies the conversion target. This must be a namespace module or similar object. def __get__(self): ------------------- def __set__(self, target): --------------------------- def __delete__(self): ---------------------- property lang: ============== The target language. The default is None. def __get__(self): ------------------- def __set__(self, lang): ------------------------- def __delete__(self): ---------------------- property makeaction: ==================== If an XIST conversion is done by an ll.make.XISTConvertAction this property will hold the action object during that conversion. If you're not using the ll.make module you can simply ignore this property. The default is None. def __get__(self): ------------------- def __set__(self, makeaction): ------------------------------- def __delete__(self): ---------------------- property makeproject: ===================== If an XIST conversion is done by an ll.make.XISTConvertAction this property will hold the Project object during that conversion. If you're not using the ll.make module you can simply ignore this property. def __get__(self): ------------------- def __set__(self, makeproject): -------------------------------- def __delete__(self): ---------------------- def push(self, node=None, root=None, mode=None, stage=None, target=None, lang=None, makeaction=None, makeproject=None): ======================================================================================================================== def pop(self): =============== def __getitem__(self, obj): ============================ Return a context object for obj, which should be an 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 Publisher(object): ========================= A Publisher object is used for serializing an XIST tree into a byte sequence. def __init__(self, encoding=None, xhtml=1, validate=True, prefixes={}, prefixdefault=False, hidexmlns=(), showxmlns=()): ========================================================================================================================= Create a publisher. Arguments have the following meaning: encoding (string 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. xhtml (int) 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 . HTML browser compatible XML (xhtml==1) Elements with an empty content model will be published as and others that just happen to be empty as . This is the default. Pure XML (xhtml==2) All empty elements will be published as . validate (bool) Specifies whether validation should be done before publishing. prefixes (mapping) 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. prefixdefault (string or None) If an element or attribute is encountered whose namespace name is not in prefixes prefixdefault is used as the fallback. hidexmlns (list 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.) showxmlns (list 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. def encode(self, text): ======================== Encode text with the encoding and error handling currently active and return the resulting byte string. def encodetext(self, text): ============================ Encode test as text data. text must be a unicode 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. def pushtextfilter(self, 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. def poptextfilter(self): ========================= Pops the current text filter function from the stack. def pusherrors(self, errors): ============================== Pushes a new error handling scheme onto the error handling stack. def poperrors(self): ===================== Pop the current error handling scheme from the error handling stack. def _newprefix(self): ====================== def getencoding(self): ======================= Return the encoding currently in effect. def getnamespaceprefix(self, 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) def getobjectprefix(self, object): =================================== Get and register a namespace prefix for the namespace object lives in (specified by the xmlns attribute of object). Similar to getnamespaceprefix this honors the namespace configuration from self.prefixes and self.prefixdefault (except when a global attribute requires a non-empty prefix). def iterbytes(self, node, base=None): ====================================== Output the node node. This method is a generator that will yield the resulting XML byte sequence in fragments. def bytes(self, node, base=None): ================================== Return a byte string in XML format for the XIST node node. def iterstring(self, node, base=None): ======================================= A generator that will produce a serialized string of node. def string(self, node, base=None): =================================== Return a unicode string for node. def write(self, stream, node, base=None): ========================================== Write node to the file-like object stream (which must provide a write method). class _Node_Meta(type): ======================== def __repr__(self): ==================== def __div__(self, other): ========================== def __floordiv__(self, other): =============================== def __mul__(self, other): ========================== def __pow__(self, other): ========================== def __and__(self, other): ========================== def __or__(self, other): ========================= def __getitem__(self, index): ============================== def __invert__(self): ====================== class Node(object): ==================== base class for nodes in the document tree. Derived classes may overwrite convert or publish. class Context(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. class __metaclass__(type): =========================== def __repr__(self): -------------------- def __div__(self, other): -------------------------- def __floordiv__(self, other): ------------------------------- def __mul__(self, other): -------------------------- def __pow__(self, other): -------------------------- def __and__(self, other): -------------------------- def __or__(self, other): ------------------------- def __getitem__(self, index): ------------------------------ def __invert__(self): ---------------------- def __repr__(self): ==================== def __ne__(self, other): ========================= def _strbase(cls, fullname, xml): ================================== def __pos__(self): =================== def __div__(self, other): ========================== def __floordiv__(self, other): =============================== def __pow__(self, other): ========================== def __and__(self, other): ========================== def __or__(self, other): ========================= def clone(self): ================= 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. def copy(self): ================ Return a shallow copy of self. def __copy__(self): ==================== def deepcopy(self): ==================== Return a deep copy of self. def __deepcopy__(self, memo=None): =================================== def present(self, *args, **kwargs): ==================================== 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. def conv(self, 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 :var:`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. def convert(self, *args, **kwargs): ==================================== 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. def __unicode__(self, *args, **kwargs): ======================================== Return the character content of self as a unicode string. This means that comments and processing instructions will be filtered out. For elements you'll get the element content. __unicode__ can be used everywhere where a plain string representation of the node is required. def __str__(self): =================== Return the character content of self as a string (if possible, i.e. there are no characters that are unencodable in the default encoding). def __int__(self): =================== Convert the character content of self to an int. def __long__(self): ==================== Convert the character content of self to an long. def asFloat(self, 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. def __float__(self): ===================== Convert the character content of self to an float. def __complex__(self): ======================= Convert the character content of self to an complex. def parsed(self, 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. def checkvalid(self): ====================== This method will be called when parsing or publishing to check whether :var`self` is valid. If self is found to be invalid a warning should be issued through the Python warning framework. def publish(self, *args, **kwargs): ==================================== Generate unicode strings for the node. publisher must be an instance of ll.xist.xsc.Publisher. The encoding and xhtml specification are taken from the publisher. def iterbytes(self, base=None, publisher=None, **publishargs): =============================================================== A generator that will produce this node as a serialized byte string. For the possible parameters see the ll.xist.xsc.Publisher constructor. def bytes(self, base=None, publisher=None, **publishargs): =========================================================== Return self as a serialized byte string. For the possible parameters see the ll.xist.xsc.Publisher constructor. def iterstring(self, base=None, publisher=None, **publishargs): ================================================================ A generator that will produce a serialized byte string of self. For the possible parameters see the ll.xist.xsc.Publisher constructor. def string(self, base=None, publisher=None, **publishargs): ============================================================ Return a serialized unicode string for self. For the possible parameters see the ll.xist.xsc.Publisher constructor. def write(self, stream, base=None, 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 ll.xist.xsc.Publisher constructor. def walk(self, walkfilter=None): ================================= Return an iterator for traversing the tree rooted at self. walkfilter is used for specifying whether or not a node should be yielded and when the children of this node should be traversed. If walkfilter is callable, it will be called for each node visited during the traversal. A path (i.e. a list of all nodes from the root to the current node) will be passed to the filter on each call and the filter must return a sequence of "node handling options". If walkfilter is not callable, it must be a sequence of node handling options that will be used for all visited nodes. Entries in this returned sequence can be the following: True This tells walk to yield this node from the iterator. False Don't yield this node from the iterator. xfind.enterattrs This is a global constant in ll.xist.xfind and tells walk to traverse the attributes of this node (if it's an Element, otherwise this option will be ignored). xfind.entercontent This is a global constant in ll.xist.xfind and tells walk to traverse the child nodes of this node (if it's an Element, otherwise this option will be ignored). These options will be executed in the order they are specified in the sequence, so to get a top down traversal of a tree (without entering attributes), (True, xfind.entercontent) can be used. For a bottom up traversal (xfind.entercontent, True) can be used. Each item produced by the iterator is a path list. walk reuses this list, so you can't rely on the value of the list being the same across calls to next. def walknodes(self, walkfilter=None): ====================================== Return an iterator for traversing the tree. filter works the same as the walkfilter argument for walk. The items produced by the iterator are the nodes themselves. def walkpaths(self, walkfilter=None): ====================================== Return an iterator for traversing the tree. walkfilter works the same as the walkfilter argument for walk. The items produced by the iterator are copies of the path. def compacted(self): ===================== Return a version of self, where textnodes or character references that contain only linefeeds are removed, i.e. potentially useless whitespace is removed. def _decoratenode(self, node): =============================== def mapped(self, 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. def normalized(self): ====================== Return a normalized version of self, which means that consecutive Text nodes are merged. def __mul__(self, factor): =========================== Return a Frag with factor times the node as an entry. Note that the node will not be copied, i.e. this is a "shallow __mul__". def __rmul__(self, factor): ============================ Return a Frag with factor times the node as an entry. def pretty(self, 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 compact before calling pretty to remove whitespace. class CharacterData(Node): =========================== Base class for XML character data (Text, ProcInst, Comment and DocType). (Provides nearly the same functionality as UserString, but omits a few methods.) def __init__(self, *content): ============================== def __getstate__(self): ======================== def __setstate__(self, content): ================================= property content: ================= The text content of the node as a unicode object. def __get__(self): ------------------- def __hash__(self): ==================== def __eq__(self, other): ========================= def __len__(self): =================== def __getitem__(self, index): ============================== def __add__(self, other): ========================== def __radd__(self, other): =========================== def __mul__(self, n): ====================== def __rmul__(self, n): ======================= def __getslice__(self, index1, index2): ======================================== def capitalize(self): ====================== def center(self, width): ========================= def count(self, sub, start=0, end=2147483647): =============================================== def endswith(self, suffix, start=0, end=2147483647): ===================================================== def index(self, sub, start=0, end=2147483647): =============================================== def isalpha(self): =================== def isalnum(self): =================== def isdecimal(self): ===================== def isdigit(self): =================== def islower(self): =================== def isnumeric(self): ===================== def isspace(self): =================== def istitle(self): =================== def isupper(self): =================== def join(self, frag): ====================== def ljust(self, width, fill=u' '): =================================== def lower(self): ================= def lstrip(self, chars=None): ============================== def replace(self, old, new, maxsplit=-1): ========================================== def rjust(self, width, fill=u' '): =================================== def rstrip(self, chars=None): ============================== def rfind(self, sub, start=0, end=2147483647): =============================================== def rindex(self, sub, start=0, end=2147483647): ================================================ def split(self, sep=None, maxsplit=-1): ======================================== def splitlines(self, keepends=0): ================================== def startswith(self, prefix, start=0, end=2147483647): ======================================================= def strip(self, chars=None): ============================= def swapcase(self): ==================== def title(self): ================= def translate(self, table): ============================ def upper(self): ================= def __repr__(self): ==================== class Text(CharacterData): =========================== A text node. The characters <, >, & (and " inside attributes) will be "escaped" with the appropriate character entities when this node is published. def convert(self, converter): ============================== def __unicode__(self): ======================= def publish(self, publisher): ============================== def present(self, presenter): ============================== def compacted(self): ===================== def pretty(self, level=0, indent='\t'): ======================================== class Frag(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. def __init__(self, *content): ============================== def __enter__(self): ===================== def __exit__(self, type, value, traceback): ============================================ def __call__(self, *content): ============================== def _str(cls, fullname=True, xml=True, decorate=True): ======================================================= def _create(self): =================== internal helper that is used to create an empty clone of self. def clear(self): ================= Make self empty. def convert(self, converter): ============================== def clone(self): ================= def __copy__(self): ==================== helper for the copy module. def __deepcopy__(self, memo=None): =================================== helper for the copy module. def present(self, presenter): ============================== def __unicode__(self): ======================= def __eq__(self, other): ========================= def publish(self, publisher): ============================== def __getitem__(self, 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 walk filters. def __setitem__(self, 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 walk filters. def __delitem__(self, 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 walk filter and any child node matching this filter will be deleted from self. def __getslice__(self, index1, index2): ======================================== Returns a slice of the content of the fragment. def __setslice__(self, index1, index2, sequence): ================================================== Replace a slice of the content of the fragment def __mul__(self, 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__ = def __mul__(self, 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__". def __iadd__(self, other): =========================== def append(self, *others): =========================== Append every item in others to self. def extend(self, items): ========================= Append all items from the sequence items to self. def insert(self, index, *others): ================================== Insert all items in others at the position index. (this is the same as self[index:index] = others) def compacted(self): ===================== def withsep(self, 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. def sorted(self, cmp=None, key=None, reverse=False): ===================================================== Return a sorted version of the self. cmp, key and reverse have to same meaning as for the builtin function sorted. def reversed(self): ==================== Return a reversed version of the self. def filtered(self, 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. def shuffled(self): ==================== Return a shuffled version of self, i.e. a copy of self where the content nodes are randomly reshuffled. def mapped(self, function, converter=None, **converterargs): ============================================================= def normalized(self): ====================== def pretty(self, level=0, indent='\t'): ======================================== def __repr__(self): ==================== class Comment(CharacterData): ============================== An XML comment. def convert(self, converter): ============================== def __unicode__(self): ======================= def present(self, presenter): ============================== def publish(self, publisher): ============================== class _DocType_Meta(_Node_Meta): ================================= def __repr__(self): ==================== class DocType(CharacterData): ============================== An XML document type declaration. class __metaclass__(_Node_Meta): ================================= def __repr__(self): -------------------- def convert(self, converter): ============================== def present(self, presenter): ============================== def publish(self, publisher): ============================== def __unicode__(self): ======================= class _ProcInst_Meta(_Node_Meta): ================================== def __repr__(self): ==================== class ProcInst(CharacterData): =============================== Base class for processing instructions. Processing instructions for specific targets must be implemented as subclasses of ProcInst. class __metaclass__(_Node_Meta): ================================= def __repr__(self): -------------------- def _str(cls, fullname=True, xml=True, decorate=True): ======================================================= def convert(self, converter): ============================== def present(self, presenter): ============================== def publish(self, publisher): ============================== def __unicode__(self): ======================= def __repr__(self): ==================== def __mul__(self, n): ====================== def __rmul__(self, n): ======================= class _Attr_Meta(_Node_Meta): ============================== def __repr__(self): ==================== class Attr(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.bytes() EGGS class __metaclass__(_Node_Meta): ================================= def __repr__(self): -------------------- def isfancy(self): =================== Return whether self contains nodes other than Text. def _str(cls, fullname=True, xml=True, decorate=True): ======================================================= def present(self, presenter): ============================== def checkvalid(self): ====================== 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. def _publishname(self, publisher): =================================== def _publishattrvalue(self, publisher): ======================================== def publish(self, publisher): ============================== def pretty(self, level=0, indent='\t'): ======================================== def __repr__(self): ==================== class TextAttr(Attr): ====================== Attribute class that is used for normal text attributes. class IDAttr(Attr): ==================== Attribute used for ids. class NumberAttr(Attr): ======================== Attribute class that is used for when the attribute value may be any kind of number. class IntAttr(NumberAttr): =========================== Attribute class that is used when the attribute value may be an integer. class FloatAttr(NumberAttr): ============================= Attribute class that is used when the attribute value may be a floating point value. class BoolAttr(Attr): ====================== Attribute class that is used for boolean attributes. When publishing the value will always be the attribute name, regardless of the real value. def publish(self, publisher): ============================== class ColorAttr(Attr): ======================= Attribute class that is used for a color attributes. class StyleAttr(Attr): ======================= Attribute class that is used for CSS style attributes. def _transform(self, replacer): ================================ def replaceurls(self, replacer): ================================= Replace each URL in the style. Each URL will be passed to the callable replacer and replaced with the returned value. def parsed(self, parser, event): ================================= def _publishattrvalue(self, publisher): ======================================== def urls(self, base=None): =========================== Return a list of all the URLs (as URL objects) found in the style attribute. class URLAttr(Attr): ===================== Attribute class that is used for URLs. See the module ll.url for more information about URL handling. def parsed(self, parser, event): ================================= def _publishattrvalue(self, publisher): ======================================== def asURL(self): ================= Return self as a URL object (note that non-Text content will be filtered out). def forInput(self, 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. def imagesize(self, root=None): ================================ Return the size of an image as a tuple. def contentlength(self, root=None): ==================================== Return the size of a file in bytes. def lastmodified(self, root=None): =================================== returns the timestamp for the last modification to the file def openread(self, root=None): =============================== Return a Resource for reading from the URL. def openwrite(self, root=None): ================================ Return a Resource for writing to the URL. class _Attrs_Meta(_Node_Meta): =============================== def __repr__(self): ==================== def __contains__(self, key): ============================= class Attrs(Node, dict): ========================= An attribute map. Allowed entries are specified through nested subclasses of Attr. class __metaclass__(_Node_Meta): ================================= def __repr__(self): -------------------- def __contains__(self, key): ----------------------------- def __init__(self, _content=None, **attrs): ============================================ def __eq__(self, other): ========================= def _str(cls, fullname=True, xml=True, decorate=True): ======================================================= def add(cls, value): ===================== def _create(self): =================== def clone(self): ================= def __copy__(self): ==================== def __deepcopy__(self, memo=None): =================================== def convert(self, converter): ============================== def compacted(self): ===================== def normalized(self): ====================== def present(self, presenter): ============================== def checkvalid(self): ====================== def publish(self, publisher): ============================== def __unicode__(self): ======================= def isallowed(cls, name): ========================== def isallowed_xml(cls, name, xmlns=None): ========================================== def __getattribute__(self, name): ================================== def __setattr__(self, name, value): ==================================== def __delattr__(self, name): ============================= def __getitem__(self, name): ============================= def __setitem__(self, name, value): ==================================== def __delitem__(self, name): ============================= def has(self, name): ===================== Return whether self has an attribute with a Python name name. name may also be an attribute class (either from self.Attrs or a global attribute). def has_xml(self, name): ========================= Similar to has, but name is treated as the XML name instead of the Python name. def __contains__(self, name): ============================== def get(self, name, default=None): =================================== works like the dictionary method get, it returns the attribute with the Python 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). def get_xml(self, name, default=None): ======================================= Similar to get, but name is treated as the XML name instead of the Python name. def set(self, name, value): ============================ Set the attribute with the Python name to the value value. name may be a string or an attribute class. The newly set attribute will be returned. def set_xml(self, name, value): ================================ Similar to set, but name is treated as the XML name instead of the Python name. def setdefault(self, 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. def setdefault_xml(self, name, default): ========================================= Similar to setdefault, but name is treated as the XML name instead of the Python name. def update(self, *args, **kwargs): =================================== Copies attributes over from all mappings in args and from kwargs. def allowedattrs(cls): ======================= Return an iterator over all allowed attribute classes. def allowedattr(cls, name): ============================ def allowedattr_xml(cls, name): ================================ def __len__(self): =================== __iter__ = def keys(self): =========================== iterkeys = def keys(self): =========================== def keys(self): ================ itervalues = def values(self): =============================== def values(self): ================== def items(self): ================= iteritems = def items(self): ============================= def _iterallvalues(self): ========================== Iterate through all values, even the unset ones. def attr(self, name): ====================== def attr_xml(self, name): ========================== def filtered(self, function): ============================== Return a filtered version of self. def _fixnames(self, names): ============================ def _fixnames_xml(self, names): ================================ def withnames(self, *names): ============================= Return a copy of self where only the attributes with Python names in names are kept, all others are removed. def withnames_xml(self, *names): ================================= Return a copy of self where only the attributes with XML names in names are kept, all others are removed. def withoutnames(self, *names): ================================ Return a copy of self where all the attributes with Python names in names are removed. def withoutnames_xml(self, *names): ==================================== Return a copy of self where all the attributes with XML names in names are removed. def __repr__(self): ==================== def _patchclassnames(dict, name): ================================== class _Element_Meta(_Node_Meta): ================================= def __repr__(self): ==================== class Element(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 with checkvalid 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. Attrs (Element.Attrs subclass) This is a class derived from Element.Attrs and must define all attributes as classes nested inside this Attrs class. xmlns (string) This is the name of the namespace this element belong to. register (bool) If register is false the element will never be registered in a Pool. The default is True. xmlname (string) 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(Node, dict): ========================= An attribute map. Allowed entries are specified through nested subclasses of Attr. class __metaclass__(_Node_Meta): --------------------------------- def __repr__(self): -------------------- def __contains__(self, key): ----------------------------- def __init__(self, _content=None, **attrs): -------------------------------------------- def __eq__(self, other): ------------------------- def _str(cls, fullname=True, xml=True, decorate=True): ------------------------------------------------------- def add(cls, value): --------------------- def _create(self): ------------------- def clone(self): ----------------- def __copy__(self): -------------------- def __deepcopy__(self, memo=None): ----------------------------------- def convert(self, converter): ------------------------------ def compacted(self): --------------------- def normalized(self): ---------------------- def present(self, presenter): ------------------------------ def checkvalid(self): ---------------------- def publish(self, publisher): ------------------------------ def __unicode__(self): ----------------------- def isallowed(cls, name): -------------------------- def isallowed_xml(cls, name, xmlns=None): ------------------------------------------ def __getattribute__(self, name): ---------------------------------- def __setattr__(self, name, value): ------------------------------------ def __delattr__(self, name): ----------------------------- def __getitem__(self, name): ----------------------------- def __setitem__(self, name, value): ------------------------------------ def __delitem__(self, name): ----------------------------- def has(self, name): --------------------- Return whether self has an attribute with a Python name name. name may also be an attribute class (either from self.Attrs or a global attribute). def has_xml(self, name): ------------------------- Similar to has, but name is treated as the XML name instead of the Python name. def __contains__(self, name): ------------------------------ def get(self, name, default=None): ----------------------------------- works like the dictionary method get, it returns the attribute with the Python 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). def get_xml(self, name, default=None): --------------------------------------- Similar to get, but name is treated as the XML name instead of the Python name. def set(self, name, value): ---------------------------- Set the attribute with the Python name to the value value. name may be a string or an attribute class. The newly set attribute will be returned. def set_xml(self, name, value): -------------------------------- Similar to set, but name is treated as the XML name instead of the Python name. def setdefault(self, 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. def setdefault_xml(self, name, default): ----------------------------------------- Similar to setdefault, but name is treated as the XML name instead of the Python name. def update(self, *args, **kwargs): ----------------------------------- Copies attributes over from all mappings in args and from kwargs. def allowedattrs(cls): ----------------------- Return an iterator over all allowed attribute classes. def allowedattr(cls, name): ---------------------------- def allowedattr_xml(cls, name): -------------------------------- def __len__(self): ------------------- __iter__ = def keys(self): --------------------------- iterkeys = def keys(self): --------------------------- def keys(self): ---------------- itervalues = def values(self): ------------------------------- def values(self): ------------------ def items(self): ----------------- iteritems = def items(self): ----------------------------- def _iterallvalues(self): -------------------------- Iterate through all values, even the unset ones. def attr(self, name): ---------------------- def attr_xml(self, name): -------------------------- def filtered(self, function): ------------------------------ Return a filtered version of self. def _fixnames(self, names): ---------------------------- def _fixnames_xml(self, names): -------------------------------- def withnames(self, *names): ----------------------------- Return a copy of self where only the attributes with Python names in names are kept, all others are removed. def withnames_xml(self, *names): --------------------------------- Return a copy of self where only the attributes with XML names in names are kept, all others are removed. def withoutnames(self, *names): -------------------------------- Return a copy of self where all the attributes with Python names in names are removed. def withoutnames_xml(self, *names): ------------------------------------ Return a copy of self where all the attributes with XML names in names are removed. def __repr__(self): -------------------- class __metaclass__(_Node_Meta): ================================= def __repr__(self): -------------------- def __init__(self, *content, **attrs): ======================================= Create a new Element instance. Positional arguments are treated as content nodes. Keyword arguments and dictionaries are treated as attributes. def __getstate__(self): ======================== def __setstate__(self, contentattrs): ====================================== def __enter__(self): ===================== 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() def __exit__(self, type, value, traceback): ============================================ def __call__(self, *content, **attrs): ======================================= Calling an element add items in content to the element content and set attributes from attrs. The element itself will be returned. def __eq__(self, other): ========================= def _str(cls, fullname=True, xml=True, decorate=True): ======================================================= def checkvalid(self): ====================== def append(self, *items): ========================== Append every item in items to the elements content. def extend(self, items): ========================= Append all items in items to the elements content. def insert(self, index, *items): ================================= Insert every item in items at the position index. def convert(self, converter): ============================== def clone(self): ================= def __copy__(self): ==================== def __deepcopy__(self, memo=None): =================================== def __unicode__(self): ======================= def _addimagesizeattributes(self, url, widthattr=None, heightattr=None): ========================================================================= Automatically set image width and height attributes. The size of the image with the URL url will be determined and the width of the image will be put into the attribute with the name widthattr if widthattr is not None and the attribute is not set already. The same will happen for the height, which will be put into the attribute named heighattr. def present(self, presenter): ============================== def _publishname(self, publisher): =================================== def _publishfull(self, publisher): =================================== Does the full publication of the element. If you need full elements inside attributes (e.g. for JSP tag libraries), you can overwrite publish and simply call this method. def publish(self, publisher): ============================== def __getitem__(self, 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. def __setitem__(self, index, value): ===================================== Set an attribute or content node to the value value. For possible types for index see __getitem__. def __delitem__(self, index): ============================== Remove an attribute or content node. For possible types for index see __getitem__. def __getslice__(self, index1, index2): ======================================== Return a copy of the element that contains a slice of the content. def __setslice__(self, index1, index2, sequence): ================================================== Replace a slice of the content of the element. def __delslice__(self, index1, index2): ======================================== Remove a slice of the content of the element. def __iadd__(self, other): =========================== def __len__(self): =================== Return the number of children. def __iter__(self): ==================== def compacted(self): ===================== def withsep(self, separator, clone=False): =========================================== Return a version of self with a separator node between the child nodes of self. For more info see Frag.withsep. def sorted(self, cmp=None, key=None, reverse=False): ===================================================== Return a sorted version of self. compare is a comparison function. The arguments cmp, key and reverse have the same meaning as fot the builtin sorted function. def reversed(self): ==================== Return a reversed version of self. def filtered(self, function): ============================== Return a filtered version of the self. def shuffled(self): ==================== Return a shuffled version of the self. def mapped(self, function, converter=None, **converterargs): ============================================================= def normalized(self): ====================== def pretty(self, level=0, indent='\t'): ======================================== def __repr__(self): ==================== class AttrElement(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). def publish(self, *args, **kwargs): ==================================== Publish self to the publisher publisher (outside of any attribute) def publishattr(self, *args, **kwargs): ======================================== Publish the attribute attr to the publisher publisher. def publishboolattr(self, *args, **kwargs): ============================================ Publish the boolean attribute attr to the publisher class _Entity_Meta(_Node_Meta): ================================ def __repr__(self): ==================== class Entity(Node): ==================== Class for entities. Derive your own entities from it and overwrite convert. class __metaclass__(_Node_Meta): ================================= def __repr__(self): -------------------- def _str(cls, fullname=True, xml=True, decorate=True): ======================================================= def __eq__(self, other): ========================= def compacted(self): ===================== def present(self, presenter): ============================== def publish(self, publisher): ============================== def __repr__(self): ==================== class _CharRef_Meta(_Entity_Meta): =================================== def __repr__(self): ==================== class CharRef(Text, Entity): ============================= A simple named character reference, the codepoint is in the class attribute codepoint. class __metaclass__(_Entity_Meta): =================================== def __repr__(self): -------------------- def __init__(self): ==================== def __getnewargs__(self): ========================== def present(self, presenter): ============================== def __getitem__(self, index): ============================== def __add__(self, other): ========================== def __radd__(self, other): =========================== def __mul__(self, n): ====================== def __rmul__(self, n): ======================= def __getslice__(self, index1, index2): ======================================== def capitalize(self): ====================== def center(self, width): ========================= def ljust(self, width, fill=u' '): =================================== def lower(self): ================= def lstrip(self, chars=None): ============================== def replace(self, old, new, maxsplit=-1): ========================================== def rjust(self, width, fill=u' '): =================================== def rstrip(self, chars=None): ============================== def strip(self, chars=None): ============================= def swapcase(self): ==================== def title(self): ================= def translate(self, table): ============================ def upper(self): ================= class Pool(ll.misc.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. def __init__(self, *objects): ============================== Create a Pool object. All items in objects will be registered in the pool. def register(self, object): ============================ Register object in the pool. object can be: * a Element, ProcInst, Entity, or CharRef 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). def __enter__(self): ===================== def __exit__(self, type, value, traceback): ============================================ def clear(self): ================= Make self empty. def clone(self): ================= Return a copy of self. def elements(self): ==================== Return an iterator for all registered element classes. def elementclass(self, name, xmlns): ===================================== Return the element class for the element with the Python name name and the namespace xmlns. If the element can't be found an IllegalElementError will be raised. def elementclass_xml(self, name, xmlns): ========================================= Return the element class for the element type with the XML name name and the namespace xmlns. If the element can't be found an IllegalElementError will be raised. def element(self, name, xmlns): ================================ Return an element object for the element type with the Python name name and the namespace xmlns. def element_xml(self, name, xmlns): ==================================== Return an element object for the element type with the XML name name and the namespace xmlns. def haselement(self, name, xmlns): =================================== Is there a registered element class in self for the element type with the Python name name and the namespace xmlns? def haselement_xml(self, name, xmlns): ======================================= Is there a registered element class in self for the element type with the XML name name and the namespace xmlns? def procinsts(self): ===================== Return an iterator for all registered processing instruction classes. def procinstclass(self, name): =============================== Return the processing instruction class for the PI with the Python name name. If the processing instruction can't be found an IllegalProcInstError will be raised. def procinstclass_xml(self, name): =================================== Return the processing instruction class for the PI with the XML name name. If the processing instruction can't be found an IllegalProcInstError will be raised. def procinst(self, name, content): =================================== Return a processing instruction object for the PI type with the Python target name name. def procinst_xml(self, name, content): ======================================= Return a processing instruction object for the PI type with the XML target name name. def hasprocinst(self, name): ============================= Is there a registered processing instruction class in self for the PI with the Python name name? def hasprocinst_xml(self, name): ================================= Is there a registered processing instruction class in self for the PI with the XML name name? def entities(self): ==================== Return an iterator for all registered entity classes. def entityclass(self, name): ============================= Return the entity class for the entity with the Python name name. If the entity can't be found an IllegalEntityError will be raised. def entityclass_xml(self, name): ================================= Return the entity class for the entity with the XML name name. If the entity can't be found an IllegalEntityError will be raised. def entity(self, name): ======================== Return an entity object for the entity with the Python name name. def entity_xml(self, name): ============================ Return an entity object for the entity with the XML name name. def hasentity(self, name): =========================== Is there a registered entity class in self for the entity with the Python name name? def hasentity_xml(self, name): =============================== Is there a registered entity class in self for the entity with the XML name name? def charrefs(self): ==================== Return an iterator for all character entity classes. def charrefclass(self, name): ============================== Return the character entity with the Python name name. name can also be an int specifying the codepoint. If the character entity can't be found a IllegalEntityError will be raised. def charrefclass_xml(self, name): ================================== Return the character entity with the XML name name. name can also be an int specifying the codepoint. If the character entity can't be found a IllegalEntityError will be raised. def charref(self, name): ========================= Return a character entity object for the character with the Python name or codepoint name. def charref_xml(self, name): ============================= Return a character entity object for the character with the XML name or codepoint name. def hascharref(self, name): ============================ Is there a registered character entity class in self with the Python name or codepoint name? def hascharref_xml(self, name): ================================ Is there a registered character entity class in self with the XML name or codepoint name? def attrclass(self, name, xmlns): ================================== Return the attribute class for the global attribute with the Python name name and the namespace xmlns. If the attribute can't be found a IllegalAttrError will be raised. def attrclass_xml(self, name, xmlns): ====================================== Return the attribute class for the global attribute with the XML name name and the namespace xmlns. If the attribute can't be found a IllegalAttrError will be raised. def text(self, content): ========================= Create a text node with the content content. def comment(self, content): ============================ Create a comment node with the content content. def __getattr__(self, key): ============================ class ThreadLocalPool(thread._local): ====================================== def docpool(): =============== Return a pool suitable for parsing XIST docstrings. def nsname(xmlns): =================== If xmlns is a module, return xmlns.xmlns, else return xmlns unchanged. def nsclark(xmlns): ==================== Return a namespace name in Clark notation. xmlns can be None, a string or a module. class quot(CharRef): ===================== quotation mark = APL quote, U+0022 ISOnum class amp(CharRef): ==================== ampersand, U+0026 ISOnum class lt(CharRef): =================== less-than sign, U+003C ISOnum class gt(CharRef): =================== greater-than sign, U+003E ISOnum class apos(CharRef): ===================== apostrophe mark, U+0027 ISOnum class Location(object): ======================== Represents a location in an XML entity. def __init__(self, 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). def offset(self, offset): ========================== Return a location where the line number is incremented by offset (and the column number is reset to 0). def __str__(self): =================== def __repr__(self): ==================== def __eq__(self, other): ========================= def __ne__(self, other): ========================= def __xattrs__(self, mode='default'): ====================================== def __xrepr__(self, mode='default'): =====================================