This module contains all the central XML tree 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 context 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 context 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. def ``__init__``​(``self``, ``attr``): -------------------------------------- def ``__str__``​(``self``): --------------------------- =================================================== class ``RequiredAttrMissingWarning``​(``Warning``): =================================================== Warning that is issued when a required attribute is missing. def ``__init__``​(``self``, ``attrs``, ``attr``): ------------------------------------------------- def ``__str__``​(``self``): --------------------------- ============================================== class ``UndeclaredAttrWarning``​(``Warning``): ============================================== Warning that is issued when a local attribute is not declared. def ``__init__``​(``self``, ``attrs``, ``attr``): ------------------------------------------------- def ``__str__``​(``self``): --------------------------- ============================================== class ``UndeclaredNodeWarning``​(``Warning``): ============================================== Warning that is issued when a node (i.e. element, entity or processing instruction) is not declared. def ``__init__``​(``self``, ``obj``): ------------------------------------- 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 ``MultipleRootsError``​(``Error``): ========================================= 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``, ``key``): ---------------------------------------- Return a context object for ``key``. Two variants are supported: * ``key`` may be a string, in which case it should be a hierarchical dot-separated name similar to Java package names (e.g. ``"org.example.project.handler"``). This helps avoid name collisions. Context objects of this type must be explicitly created via ``__setitem__``. * ``key`` may be a ``ll.xist.xsc.Node`` instance or subclass. Each of these classes that defines its own ``Context`` class gets a unique instance of this class. This instance will be created on the first access and the element can store information there that needs to be available across calls to ``convert``. def ``__setitem__``​(``self``, ``key``, ``value``): --------------------------------------------------- ================================= 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``=``False``, ``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 ``str`` object. The publisher will apply the configured encoding, error handling and the current text filter (which escapes characters that can't appear in text data (like ``<`` etc.)) and returns the resulting ``str`` object. 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``, ``allowschemerelurls``=``False``): -------------------------------------------------------------------------------------------- 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``, ``allowschemerelurls``=``False``): ---------------------------------------------------------------------------------------- Return a ``bytes`` object in XML format for the XIST node ``node``. def ``iterstring``​(``self``, ``node``, ``base``=``None``, ``allowschemerelurls``=``False``): --------------------------------------------------------------------------------------------- A generator that will produce a serialized string of ``node``. def ``string``​(``self``, ``node``, ``base``=``None``, ``allowschemerelurls``=``False``): ----------------------------------------------------------------------------------------- Return a string for ``node``. def ``write``​(``self``, ``stream``, ``node``, ``base``=``None``, ``allowschemerelurls``=``False``): ---------------------------------------------------------------------------------------------------- Write ``node`` to the file-like object ``stream`` (which must provide a ``write`` method). ============================== class ``Cursor``​(``object``): ============================== A ``Cursor`` object is used by the ``walk`` method during tree traversal. It contains information about the state of the traversal and can be used to influence which parts of the tree are traversed and in which order. Information about the state of the traversal is provided in the following attributes: ``root`` The node where traversal has been started (i.e. the object for which the ``walk`` method has been called). ``node`` The current node being traversed. ``path`` A list of nodes that contains the path through the tree from the root to the current node (i.e. ``path[0] is root`` and ``path[-1] is node``). ``index`` A path of indices (e.g. ``[0, 1]`` if the current node is the second child of the first child of the root). Inside attributes the index path will contain the name of the attribute (or a (attribute name, namespace name) tuple inside a global attribute). ``event`` A string that specifies which event is currently handled. Possible values are: ``"enterelementnode"``, ``"leaveelementnode"``, ``"enterattrnode"``, ``"leaveattrnode"``, ``"textnode"``, ``"commentnode"``, ``"doctypenode"``, ``"procinstnode"``, ``"entitynode"`` and ``"nullnode"``. The following attributes specify which part of the tree should be traversed: ``entercontent`` Should the content of an element be entered? ``enterattrs`` Should the attributes of an element be entered? (Note that the attributes will always be entered before the content.) ``enterattr`` Should the content of the attributes of an element be entered? (This is only relevant if ``enterattrs`` is true.) ``enterelementnode`` Should the generator yield a ``"enterelementnode"`` event (i.e. return before entering the content or attributes of an element)? ``leaveelementnode`` Should the generator yield an ``"leaveelementnode"`` event (i.e. return after entering the content or attributes of an element)? ``enterattrnode`` Should the generator yield a ``"enterattrnode"`` event (i.e. return before entering the content of an attribute)? This is only relevant if ``enterattrs`` is true. ``leaveattrnode`` Should the generator yield an ``"leaveattrnode"`` event (i.e. return after entering the content of an attribute)? This is only relevant if ``enterattrs`` is true. Furthermore if ``enterattr`` is false, the behaviour is essentially the same as for ``enterattrnode``. Note that if any of these attributes is changed by the code consuming the generator, this new value will be used for the next traversal step once the generator is resumed and will be reset to its initial value (specified in the constructor) afterwards. def ``__init__``​(``self``, ``node``, ``entercontent``=``True``, ``enterattrs``=``False``, ``enterattr``=``False``, ``enterelementnode``=``True``, ``leaveelementnode``=``False``, ``enterattrnode``=``True``, ``leaveattrnode``=``False``): -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a new ``Cursor`` object for a tree traversal rooted at the node ``node``. The arguments ``entercontent``, ``enterattrs``, ``enterattr``, ``enterelementnode``, ``leaveelementnode``, ``enterattrnode`` and ``leaveattrnode`` are used as the initial values for the attributes of the same name. (see the class docstring for info about their use). def ``restore``​(``self``): --------------------------- Restore the attributes ``entercontent``, ``enterattrs``, ``enterattr``, ``enterelementnode``, ``leaveelementnode``, ``enterattrnode`` and ``leaveattrnode`` to their initial value. ================================ class ``_Node_Meta``​(``type``): ================================ def ``__new__``​(``cls``, ``name``, ``bases``, ``dict``): --------------------------------------------------------- def ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``__contains__``​(``self``, ``path``): ------------------------------------------ def ``__truediv__``​(``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. def ``__repr__``​(``self``): ---------------------------- def ``__ne__``​(``self``, ``other``): ------------------------------------- def ``__pos__``​(``self``): --------------------------- def ``__truediv__``​(``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 ``:obj:`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 ``__str__``​(``self``, *``args``, **``kwargs``): ---------------------------------------------------- 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 def ``__int__``​(``self``): --------------------------- Convert the character content of ``self`` to an ``int``. 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 ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- 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``, ``allowschemerelurls``=``False``, ``publisher``=``None``, **``publishargs``): ----------------------------------------------------------------------------------------------------------------------------- A generator that will produce this node as a serialized byte string. (i.e. it will output what the method ``bytes`` outputs, but incremetally). For the possible parameters see the ``ll.xist.xsc.Publisher`` constructor. def ``bytes``​(``self``, ``base``=``None``, ``allowschemerelurls``=``False``, ``publisher``=``None``, **``publishargs``): ------------------------------------------------------------------------------------------------------------------------- Return ``self`` as a serialized bytes object. For the possible parameters see the ``ll.xist.xsc.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'

The header

The content

' def ``iterstring``​(``self``, ``base``=``None``, ``allowschemerelurls``=``False``, ``publisher``=``None``, **``publishargs``): ------------------------------------------------------------------------------------------------------------------------------ A generator that will produce a serialized string of ``self`` (i.e. it will output what the method ``string`` outputs, but incremetally). For the possible parameters see the ``ll.xist.xsc.Publisher`` constructor. def ``string``​(``self``, ``base``=``None``, ``allowschemerelurls``=``False``, ``publisher``=``None``, **``publishargs``): -------------------------------------------------------------------------------------------------------------------------- Return a serialized (unicode) string for ``self``. For the possible parameters see the ``ll.xist.xsc.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())

The header

The content

def ``write``​(``self``, ``stream``, ``base``=``None``, ``allowschemerelurls``=``False``, ``publisher``=``None``, **``publishargs``): ------------------------------------------------------------------------------------------------------------------------------------- Write ``self`` to the file-like object ``stream`` (which must provide a ``write`` method). For the rest of the parameters see the ``ll.xist.xsc.Publisher`` constructor. def ``_walk``​(``self``, ``cursor``): ------------------------------------- def ``walk``​(``self``, *``selectors``, ``entercontent``=``True``, ``enterattrs``=``False``, ``enterattr``=``False``, ``enterelementnode``=``True``, ``leaveelementnode``=``False``, ``enterattrnode``=``True``, ``leaveattrnode``=``False``): ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Return an iterator for traversing the tree rooted at ``self``. Each item produced by the iterator is a ``Cursor`` object. It contains information about the state of the traversal and can be used to influence which parts of the tree are traversed and in which order. ``selectors`` is used for filtering which nodes to return from the iterator. The arguments ``entercontent``, ``enterattrs``, ``enterattr``, ``enterelementnode``, ``leaveelementnode``, ``enterattrnode`` and ``leaveattrnode`` specify how the tree should be traversed. For more information see the ``Cursor`` class. Note that the ``Cursor`` object is reused by ``walk``, so you can't rely on any attributes remaining the same across calls to ``next``. The following example shows how to extract the text of an HTML ``label`` element for an input element with a specified HTML id: from ll import misc from ll.xist import xsc, xfind from ll.xist.ns import html def label(doc, id): label = misc.first(doc.walk(xfind.attrhasvalue("for", id)), None) if label is None: return None texts = [] for c in label.node.walk(html.textarea, xsc.Text): if isinstance(c.node, html.textarea): c.entercontent = False else: texts.append(str(c.node)) return " ".join("".join(texts).split()).strip() doc = html.div( html.p( html.label( "Input your text here: ", html.textarea("Default value", rows=20, cols=80, id="foo"), " (just a test)", for_="foo", ) ) ) print(repr(label(doc, "foo"))) This will output: 'Input your text here: (just a test)' def ``walknodes``​(``self``, *``selectors``, ``entercontent``=``True``, ``enterattrs``=``False``, ``enterattr``=``False``, ``enterelementnode``=``True``, ``leaveelementnode``=``False``, ``enterattrnode``=``True``, ``leaveattrnode``=``False``): --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Return an iterator for traversing the tree. The arguments have the same meaning as those for ``walk``. The items produced by the iterator are the nodes themselves. def ``walkpaths``​(``self``, *``selectors``, ``entercontent``=``True``, ``enterattrs``=``False``, ``enterattr``=``False``, ``enterelementnode``=``True``, ``leaveelementnode``=``False``, ``enterattrnode``=``True``, ``leaveattrnode``=``False``): --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Return an iterator for traversing the tree. The arguments have the same meaning as those for ``walk``. The items produced by the iterator are copies of the path. 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 ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``__getstate__``​(``self``): -------------------------------- def ``__setstate__``​(``self``, ``content``): --------------------------------------------- property content: ----------------- The text content of the node as a ``str`` object. def ``__get__``​(``self``): """"""""""""""""""""""""""" def ``__hash__``​(``self``): ---------------------------- def ``__eq__``​(``self``, ``other``): ------------------------------------- def ``__lt__``​(``self``, ``other``): ------------------------------------- def ``__le__``​(``self``, ``other``): ------------------------------------- def ``__gt__``​(``self``, ``other``): ------------------------------------- def ``__ge__``​(``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 ``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``=``' '``): ------------------------------------------------------ def ``lower``​(``self``): ------------------------- def ``lstrip``​(``self``, ``chars``=``None``): ---------------------------------------------- def ``replace``​(``self``, ``old``, ``new``, ``maxsplit``=``-1``): ------------------------------------------------------------------ def ``rjust``​(``self``, ``width``, ``fill``=``' '``): ------------------------------------------------------ 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``): ------------------------- =================================== 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 ``__str__``​(``self``): --------------------------- def ``_str``​(``self``): ------------------------ def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``compacted``​(``self``): ----------------------------- def ``pretty``​(``self``, ``level``=``0``, ``indent``=``'\t'``): ---------------------------------------------------------------- def ``_walk``​(``self``, ``cursor``): ------------------------------------- ==================================== 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 ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``__str__``​(``self``): --------------------------- def ``_str``​(``self``): ------------------------ def ``__enter__``​(``self``): ----------------------------- def ``__exit__``​(``self``, ``type``, ``value``, ``traceback``): ---------------------------------------------------------------- def ``__call__``​(``self``, *``content``): ------------------------------------------ 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 ``__eq__``​(``self``, ``other``): ------------------------------------- def ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- 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 selectors (i.e. ``xfind.Selector`` objects). 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 selectors (i.e. ``xfind.Selector`` objects). 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 selector (i.e. an ``xfind.Selector`` objects) and any child node matching this selector will be deleted from ``self``. 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 ``__rmul__``​(``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 ``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 ``_walk``​(``self``, ``cursor``): ------------------------------------- ====================================== class ``Comment``​(``CharacterData``): ====================================== An XML comment. def ``__str__``​(``self``): --------------------------- def ``_str``​(``self``): ------------------------ def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``_walk``​(``self``, ``cursor``): ------------------------------------- ========================================= class ``_DocType_Meta``​(``_Node_Meta``): ========================================= def ``__repr__``​(``self``): ---------------------------- ====================================== class ``DocType``​(``CharacterData``): ====================================== An XML document type declaration. def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``__str__``​(``self``): --------------------------- def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``_walk``​(``self``, ``cursor``): ------------------------------------- ========================================== class ``_ProcInst_Meta``​(``_Node_Meta``): ========================================== def ``__new__``​(``cls``, ``name``, ``bases``, ``dict``): --------------------------------------------------------- def ``__repr__``​(``self``): ---------------------------- ======================================= class ``ProcInst``​(``CharacterData``): ======================================= Base class for processing instructions. Processing instructions for specific targets must be implemented as subclasses of ``ProcInst``. def ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``__str__``​(``self``): --------------------------- def ``_str``​(``self``): ------------------------ def ``__eq__``​(``self``, ``other``): ------------------------------------- def ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``_walk``​(``self``, ``cursor``): ------------------------------------- def ``__mul__``​(``self``, ``n``): ---------------------------------- def ``__rmul__``​(``self``, ``n``): ----------------------------------- ====================================== class ``_Attr_Meta``​(``_Node_Meta``): ====================================== def ``__new__``​(``cls``, ``name``, ``bases``, ``dict``): --------------------------------------------------------- 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.string()) EGGS def ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``_str``​(``self``): ------------------------ def ``_create``​(``self``): --------------------------- def ``isfancy``​(``self``): --------------------------- Return whether ``self`` contains nodes other than ``Text``. def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- Check whether ``self`` has an allowed value, i.e. one that is specified in the class attribute ``values``. If the value is not allowed a warning will be issued through the Python warning framework. If ``self`` is "fancy" (i.e. contains non-``Text`` nodes), no check will be done. def ``_publishname``​(``self``, ``publisher``): ----------------------------------------------- def ``_publishattrvalue``​(``self``, ``publisher``): ---------------------------------------------------- def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``pretty``​(``self``, ``level``=``0``, ``indent``=``'\t'``): ---------------------------------------------------------------- def ``_walk``​(``self``, ``cursor``): ------------------------------------- ============================== 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 ``__new__``​(``cls``, ``name``, ``bases``, ``dict``): --------------------------------------------------------- def ``__repr__``​(``self``): ---------------------------- def ``_attrinfo``​(``self``, ``name``): --------------------------------------- def ``__contains__``​(``self``, ``key``): ----------------------------------------- ===================================== class ``Attrs``​(``Node``, ``dict``): ===================================== An attribute map. Predefined attribute can be declared through nested subclasses of ``Attr``. def ``__init__``​(``self``, *``args``, **``kwargs``): ----------------------------------------------------- def ``__repr__``​(``self``): ---------------------------- def ``_sortorder``​(``attrvalue``): ----------------------------------- def ``_repr_pretty_content_``​(``self``, ``p``): ------------------------------------------------ def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``__str__``​(``self``): --------------------------- def ``_str``​(``self``): ------------------------ def ``__eq__``​(``self``, ``other``): ------------------------------------- def ``_create``​(``self``): --------------------------- def ``clone``​(``self``): ------------------------- def ``__copy__``​(``self``): ---------------------------- def ``__deepcopy__``​(``self``, ``memo``=``None``): --------------------------------------------------- def ``__getitem__``​(``self``, ``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 def ``__setitem__``​(``self``, ``name``, ``value``): ---------------------------------------------------- Set the attribute with the XML ``name`` to the value ``value``. ``name`` may be a string or an attribute class or instance. The newly set attribute object will be returned. def ``__delitem__``​(``self``, ``name``): ----------------------------------------- def ``__contains__``​(``self``, ``name``): ------------------------------------------ def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``compacted``​(``self``): ----------------------------- def ``normalized``​(``self``): ------------------------------ def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- def ``validateattr``​(``self``, ``path``): ------------------------------------------ def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``__getattribute__``​(``self``, ``name``): ---------------------------------------------- def ``__setattr__``​(``self``, ``name``, ``value``): ---------------------------------------------------- def ``__delattr__``​(``self``, ``name``): ----------------------------------------- def ``get``​(``self``, ``name``, ``default``=``None``): ------------------------------------------------------- Works like the dictionary method ``get``, it returns the attribute with the XML name ``name``, or ``default`` if ``self`` has no such attribute. ``name`` may also be an attribute class (either from ``self.Attrs`` or a global attribute). 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 ``update``​(``self``, *``args``, **``kwargs``): --------------------------------------------------- Copies attributes over from all mappings in ``args`` and from ``kwargs``. Keywords are treated as the Python names of attributes. def ``__len__``​(``self``): --------------------------- def ``__iter__``​(``self``): ---------------------------- def ``keys``​(``self``): ------------------------ def ``values``​(``self``): -------------------------- def ``items``​(``self``): ------------------------- def ``filtered``​(``self``, ``function``): ------------------------------------------ Return a filtered version of ``self``. def ``_fixnames``​(``self``, ``names``): ---------------------------------------- def ``withnames``​(``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 XML names in ``names`` are removed. def ``_walk``​(``self``, ``cursor``): ------------------------------------- ========================================= class ``_Element_Meta``​(``_Node_Meta``): ========================================= def ``__new__``​(``cls``, ``name``, ``bases``, ``dict``): --------------------------------------------------------- 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 ``validate`` method) This is an object that is used for validating the content of the element. See the module ``ll.xist.sims`` for more info. If ``model`` is ``None`` validation will be skipped, otherwise it will be performed when parsing or publishing. ``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. Predefined attribute can be declared through nested subclasses of ``Attr``. def ``__init__``​(``self``, *``args``, **``kwargs``): """"""""""""""""""""""""""""""""""""""""""""""""""""" def ``__repr__``​(``self``): """""""""""""""""""""""""""" def ``_sortorder``​(``attrvalue``): """"""""""""""""""""""""""""""""""" def ``_repr_pretty_content_``​(``self``, ``p``): """""""""""""""""""""""""""""""""""""""""""""""" def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): """"""""""""""""""""""""""""""""""""""""""""""""""" def ``__str__``​(``self``): """"""""""""""""""""""""""" def ``_str``​(``self``): """""""""""""""""""""""" def ``__eq__``​(``self``, ``other``): """"""""""""""""""""""""""""""""""""" def ``_create``​(``self``): """"""""""""""""""""""""""" def ``clone``​(``self``): """"""""""""""""""""""""" def ``__copy__``​(``self``): """""""""""""""""""""""""""" def ``__deepcopy__``​(``self``, ``memo``=``None``): """"""""""""""""""""""""""""""""""""""""""""""""""" def ``__getitem__``​(``self``, ``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 def ``__setitem__``​(``self``, ``name``, ``value``): """""""""""""""""""""""""""""""""""""""""""""""""""" Set the attribute with the XML ``name`` to the value ``value``. ``name`` may be a string or an attribute class or instance. The newly set attribute object will be returned. def ``__delitem__``​(``self``, ``name``): """"""""""""""""""""""""""""""""""""""""" def ``__contains__``​(``self``, ``name``): """""""""""""""""""""""""""""""""""""""""" def ``convert``​(``self``, ``converter``): """""""""""""""""""""""""""""""""""""""""" def ``compacted``​(``self``): """"""""""""""""""""""""""""" def ``normalized``​(``self``): """""""""""""""""""""""""""""" def ``present``​(``self``, ``presenter``): """""""""""""""""""""""""""""""""""""""""" def ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" def ``validateattr``​(``self``, ``path``): """""""""""""""""""""""""""""""""""""""""" def ``publish``​(``self``, ``publisher``): """""""""""""""""""""""""""""""""""""""""" def ``__getattribute__``​(``self``, ``name``): """""""""""""""""""""""""""""""""""""""""""""" def ``__setattr__``​(``self``, ``name``, ``value``): """""""""""""""""""""""""""""""""""""""""""""""""""" def ``__delattr__``​(``self``, ``name``): """"""""""""""""""""""""""""""""""""""""" def ``get``​(``self``, ``name``, ``default``=``None``): """"""""""""""""""""""""""""""""""""""""""""""""""""""" Works like the dictionary method ``get``, it returns the attribute with the XML name ``name``, or ``default`` if ``self`` has no such attribute. ``name`` may also be an attribute class (either from ``self.Attrs`` or a global attribute). 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 ``update``​(``self``, *``args``, **``kwargs``): """"""""""""""""""""""""""""""""""""""""""""""""""" Copies attributes over from all mappings in ``args`` and from ``kwargs``. Keywords are treated as the Python names of attributes. def ``__len__``​(``self``): """"""""""""""""""""""""""" def ``__iter__``​(``self``): """""""""""""""""""""""""""" def ``keys``​(``self``): """""""""""""""""""""""" def ``values``​(``self``): """""""""""""""""""""""""" def ``items``​(``self``): """"""""""""""""""""""""" def ``filtered``​(``self``, ``function``): """""""""""""""""""""""""""""""""""""""""" Return a filtered version of ``self``. def ``_fixnames``​(``self``, ``names``): """""""""""""""""""""""""""""""""""""""" def ``withnames``​(``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 XML names in ``names`` are removed. def ``_walk``​(``self``, ``cursor``): """"""""""""""""""""""""""""""""""""" 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 ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``__str__``​(``self``): --------------------------- def ``_str``​(``self``): ------------------------ def ``__getstate__``​(``self``): -------------------------------- def ``__setstate__``​(``self``, ``data``): ------------------------------------------ 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 ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- 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 ``_create``​(``self``): --------------------------- def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``clone``​(``self``): ------------------------- def ``__copy__``​(``self``): ---------------------------- def ``__deepcopy__``​(``self``, ``memo``=``None``): --------------------------------------------------- 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 ``__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 ``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 ``_walk``​(``self``, ``cursor``): ------------------------------------- ==================================== 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 ``__new__``​(``cls``, ``name``, ``bases``, ``dict``): --------------------------------------------------------- def ``__repr__``​(``self``): ---------------------------- ============================ class ``Entity``​(``Node``): ============================ Class for entities. Derive your own entities from it and overwrite ``convert``. def ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- def ``_str``​(``self``): ------------------------ def ``__eq__``​(``self``, ``other``): ------------------------------------- def ``validate``​(``self``, ``recursive``=``True``, ``path``=``None``): ----------------------------------------------------------------------- def ``convert``​(``self``, ``converter``): ------------------------------------------ def ``compacted``​(``self``): ----------------------------- def ``present``​(``self``, ``presenter``): ------------------------------------------ def ``publish``​(``self``, ``publisher``): ------------------------------------------ def ``_walk``​(``self``, ``cursor``): ------------------------------------- =========================================== class ``_CharRef_Meta``​(``_Entity_Meta``): =========================================== def ``__repr__``​(``self``): ---------------------------- ========================================= class ``CharRef``​(``Text``, ``Entity``): ========================================= A simple named character reference, the code point is in the class attribute ``codepoint``. def ``__init__``​(``self``): ---------------------------- def ``__repr__``​(``self``): ---------------------------- def ``_repr_pretty_``​(``self``, ``p``, ``cycle``): --------------------------------------------------- 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 ``capitalize``​(``self``): ------------------------------ def ``center``​(``self``, ``width``): ------------------------------------- def ``ljust``​(``self``, ``width``, ``fill``=``' '``): ------------------------------------------------------ def ``lower``​(``self``): ------------------------- def ``lstrip``​(``self``, ``chars``=``None``): ---------------------------------------------- def ``replace``​(``self``, ``old``, ``new``, ``maxsplit``=``-1``): ------------------------------------------------------------------ def ``rjust``​(``self``, ``width``, ``fill``=``' '``): ------------------------------------------------------ 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`` or ``Entity`` class; * an ``Attr`` class for a global attribute; * an ``Attrs`` class containing global attributes; * a ``dict`` (all values will be registered, this makes it possible to e.g. register all local variables by passing ``vars()``); * a module (all attributes in the module will be registered). 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``, ``xmlns``, ``name``): ----------------------------------------------------- Return the element class for the element with the XML name ``name`` and the namespace ``xmlns``. If the element can't be found an ``Element`` will be returned. def ``element``​(``self``, ``xmlns``, ``name``): ------------------------------------------------ Return an element object for the element type with the XML name ``name`` and the namespace ``xmlns``. def ``haselement``​(``self``, ``xmlns``, ``name``): --------------------------------------------------- Is there a registered element class in ``self`` for the element type with the Python 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 target name ``name``. If the processing instruction can't be found an return ``ProcInst``. def ``procinst``​(``self``, ``name``, ``content``): --------------------------------------------------- Return a processing instruction object for the PI type with the target name ``name``. def ``hasprocinst``​(``self``, ``name``): ----------------------------------------- Is there a registered processing instruction class in ``self`` for the PI with the target 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 XML name ``name``. If the entity can't be found return ``Entity``. def ``entity``​(``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 XML name ``name``? def ``attrkey``​(``self``, ``xmlns``, ``name``): ------------------------------------------------ Return the key that can be used to set the attribute with the name ``name`` and the namespace ``xmlns``. If ``self`` (or one of the base pools) has any global attribute registered for that name/namespace, the attribute class will be returned. Otherwise the tuple ``(name, xmlns)`` (or ``name`` itself for a local attribute) will be returned. With this key ``Attrs.__setitem__`` will create the appropriate attribute class. 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``​(``obj``): ========================== Return a name in Clark notation. ``xmlns`` can be ``None``, a string or a module to return a namespace name, or a ``Node`` instance of subclass to return a namespace name + node name combination: >>> from ll.xist import xsc >>> from ll.xist.ns import html >>> xsc.nsclark(None) '{}' >>> xsc.nsclark(html) '{http://www.w3.org/1999/xhtml}' >>> xsc.nsclark(html.a) '{http://www.w3.org/1999/xhtml}a' >>> xsc.nsclark(html.a()) '{http://www.w3.org/1999/xhtml}a' ============================= class ``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 ==================================================================== def ``element``​(``xmlns``, ``xmlname``, *``content``, **``attrs``): ==================================================================== Create a plain element object with the namespace name ``xmlns`` and the element name ``xmlname``. This object will be an instance of ``Element`` (not an instance of a subclass). ``content`` and ``attrs`` will be used to initialize the content and attributes of the element. ============================= def ``entity``​(``xmlname``): ============================= Create a plain entity object with the entity name ``xmlname``. This object will be an instance of ``Entity`` (not an instance of a subclass). ============================================= def ``procinst``​(``xmlname``, *``content``): ============================================= Create a plain processing instruction object the target ``xmlname``. This object will be an instance of ``ProcInsst`` (not an instance of a subclass). ``content`` and ``attrs`` will be used to initialize the content of the processing instruction. ================================ 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``): -------------------------------------