zope.structuredtext API

zope.structuredtext.document

Structured text document parser

class zope.structuredtext.document.Document

Class instance calls [ex.=> x()] require a structured text structure. Doc will then parse each paragraph in the structure and will find the special structures within each paragraph. Each special structure will be stored as an instance. Special structures within another special structure are stored within the ‘top’ structure EX : ‘-underline this-’ => would be turned into an underline instance. ‘-underline this’ would be stored as an underline instance with a strong instance stored in its string

parse(raw_string, text_type, type=<class 'type'>)

Parse accepts a raw_string, an expr to test the raw_string, and the raw_string’s subparagraphs.

Parse will continue to search through raw_string until all instances of expr in raw_string are found.

If no instances of expr are found, raw_string is returned. Otherwise a list of substrings and instances is returned

color_text(text, types=None)

Search the paragraph for each special structure

doc_sgml(s, expr=<built-in method search of re.Pattern object>)

SGML text is ignored and outputed as-is

class zope.structuredtext.document.DocumentWithImages

Document with images

zope.structuredtext.stletters

Structured text character classes

zope.structuredtext.stng

Core document model.

zope.structuredtext.stng.indention(str, front=<built-in method match of re.Pattern object>)

Find the number of leading spaces. If none, return 0.

zope.structuredtext.stng.insert(struct, top, level)

Find what will be the parant paragraph of a sentence and return that paragraph’s sub-paragraphs. The new paragraph will be appended to those sub-paragraphs

zope.structuredtext.stng.display(struct)

Runs through the structure and prints out the paragraphs. If the insertion works correctly, display’s results should mimic the orignal paragraphs.

zope.structuredtext.stng.display2(struct)

Runs through the structure and prints out the paragraphs. If the insertion works correctly, display’s results should mimic the orignal paragraphs.

zope.structuredtext.stng.findlevel(levels, indent)

Remove all level information of levels with a greater level of indentation. Then return which level should insert this paragraph

zope.structuredtext.stng.structurize(paragraphs, delimiter=re.compile('(\\n\\s*\\n|\\r\\n\\s*\\r\\n)'))

Accepts paragraphs, which is a list of lines to be parsed. structurize creates a structure which mimics the structure of the paragraphs. Structure => [paragraph,[sub-paragraphs]]

class zope.structuredtext.stng.StructuredTextParagraph(src, subs=None, **kw)

getChildren()

Get a Python sequence of children

class zope.structuredtext.stng.StructuredTextDocument(subs=None, **kw)

A StructuredTextDocument holds StructuredTextParagraphs as its subparagraphs.

getChildren()

Get a Python sequence of children

class zope.structuredtext.stng.StructuredTextExample(subs, **kw)

Represents a section of document with literal text, as for examples

class zope.structuredtext.stng.StructuredTextBullet(src, subs=None, **kw)

Represents a section of a document with a title and a body

class zope.structuredtext.stng.StructuredTextNumbered(src, subs=None, **kw)

Represents a section of a document with a title and a body

class zope.structuredtext.stng.StructuredTextDescriptionTitle(src, subs=None, **kw)

Represents a section of a document with a title and a body

class zope.structuredtext.stng.StructuredTextDescriptionBody(src, subs=None, **kw)

Represents a section of a document with a title and a body

class zope.structuredtext.stng.StructuredTextDescription(title, src, subs, **kw)

Represents a section of a document with a title and a body

getChildren()

Get a Python sequence of children

class zope.structuredtext.stng.StructuredTextSectionTitle(src, subs=None, **kw)

Represents a section of a document with a title and a body

class zope.structuredtext.stng.StructuredTextSection(src, subs=None, **kw)

Represents a section of a document with a title and a body

class zope.structuredtext.stng.StructuredTextTable(rows, src, subs, **kw)

rows is a list of lists containing tuples, which represent the columns/cells in each rows. EX rows = [[(‘row 1:column1’,1)],[(‘row2:column1’,1)]]

getColorizableTexts()

return a tuple where each item is a column/cell’s contents. The tuple, result, will be of this format. (“r1 col1”, “r1=col2”, “r2 col1”, “r2 col2”)

setColorizableTexts(texts)

texts is going to a tuple where each item is the result of being mapped to the colortext function. Need to insert the results appropriately into the individual columns/cells

class zope.structuredtext.stng.StructuredTextRow(row, kw)

row is a list of tuples, where each tuple is the raw text for a cell/column and the span of that cell/column. EX [(‘this is column one’,1), (‘this is column two’,1)]

class zope.structuredtext.stng.StructuredTextColumn(text, span, align, valign, typ, kw)

StructuredTextColumn is a cell/column in a table. A cell can hold multiple paragraphs. The cell is either classified as a StructuredTextTableHeader or StructuredTextTableData.

class zope.structuredtext.stng.StructuredTextTableHeader(src, subs=None, **kw)

class zope.structuredtext.stng.StructuredTextTableData(src, subs=None, **kw)

class zope.structuredtext.stng.StructuredTextMarkup(value, **kw)

getChildren()

Get a Python sequence of children

class zope.structuredtext.stng.StructuredTextLiteral(value, **kw)

class zope.structuredtext.stng.StructuredTextEmphasis(value, **kw)

class zope.structuredtext.stng.StructuredTextStrong(value, **kw)

class zope.structuredtext.stng.StructuredTextInnerLink(value, **kw)

class zope.structuredtext.stng.StructuredTextNamedLink(value, **kw)

class zope.structuredtext.stng.StructuredTextUnderline(value, **kw)

class zope.structuredtext.stng.StructuredTextSGML(value, **kw)

class zope.structuredtext.stng.StructuredTextLink(value, **kw)

class zope.structuredtext.stng.StructuredTextXref(value, **kw)

class zope.structuredtext.stng.StructuredTextImage(value, **kw)

A simple embedded image

zope.structuredtext.stdom

DOM implementation in StructuredText: read-only methods

exception zope.structuredtext.stdom.DOMException

exception zope.structuredtext.stdom.IndexSizeException

exception zope.structuredtext.stdom.DOMStringSizeException

exception zope.structuredtext.stdom.HierarchyRequestException

exception zope.structuredtext.stdom.WrongDocumentException

exception zope.structuredtext.stdom.InvalidCharacterException

exception zope.structuredtext.stdom.NoDataAllowedException

exception zope.structuredtext.stdom.NoModificationAllowedException

exception zope.structuredtext.stdom.NotFoundException

exception zope.structuredtext.stdom.NotSupportedException

exception zope.structuredtext.stdom.InUseAttributeException

class zope.structuredtext.stdom.ParentNode

A node that can have children, or, more precisely, that implements the child access methods of the DOM.

getChildNodes(type=<class 'type'>, sts=<class 'str'>)

Returns a NodeList that contains all children of this node. If there are no children, this is a empty NodeList

getFirstChild(type=<class 'type'>, sts=<class 'str'>)

The first child of this node. If there is no such node this returns None

getLastChild(type=<class 'type'>, sts=<class 'str'>)

The last child of this node. If there is no such node this returns None.

class zope.structuredtext.stdom.NodeWrapper(aq_self, aq_parent)

This is an acquisition-like wrapper that provides parent access for DOM sans circular references!

getParentNode()

The parent of this node. All nodes except Document DocumentFragment and Attr may have a parent

getPreviousSibling()

The node immediately preceding this node. If there is no such node, this returns None.

getNextSibling()

The node immediately preceding this node. If there is no such node, this returns None.

getOwnerDocument()

The Document object associated with this node, if any.

class zope.structuredtext.stdom.Node

Node Interface

getNodeName()

The name of this node, depending on its type

getNodeValue()

The value of this node, depending on its type

getParentNode()

The parent of this node. All nodes except Document DocumentFragment and Attr may have a parent

getChildren()

Get a Python sequence of children

getPreviousSibling()

The node immediately preceding this node. If there is no such node, this returns None.

getNextSibling()

The node immediately preceding this node. If there is no such node, this returns None.

getAttributes()

Returns a NamedNodeMap containing the attributes of this node (if it is an element) or None otherwise.

getOwnerDocument()

The Document object associated with this node, if any.

hasChildNodes()

Returns true if the node has any children, false if it doesn’t.

getNodeType()

A code representing the type of the node.

class zope.structuredtext.stdom.TextNode(str)

getNodeName()

The name of this node, depending on its type

getNodeValue()

The value of this node, depending on its type

class zope.structuredtext.stdom.Element

Element interface

getTagName()

The name of the element

getNodeName()

The name of the element

getNodeValue()

The value of this node, depending on its type

getParentNode()

The parent of this node. All nodes except Document DocumentFragment and Attr may have a parent

getAttribute(name)

Retrieves an attribute value by name.

getAttributeNode(name)

Retrieves an Attr node by name or None if there is no such attribute.

getAttributes()

Returns a NamedNodeMap containing the attributes of this node (if it is an element) or None otherwise.

getElementsByTagName(tagname)

Returns a NodeList of all the Elements with a given tag name in the order in which they would be encountered in a preorder traversal of the Document tree. Parameter: tagname The name of the tag to match (* = all tags). Return Value: A new NodeList object containing all the matched Elements.

class zope.structuredtext.stdom.NodeList(list=None)

NodeList interface - Provides the abstraction of an ordered collection of nodes.

Python extensions: can use sequence-style ‘len’, ‘getitem’, and ‘for..in’ constructs.

item(index)

Returns the index-th item in the collection

getLength()

The length of the NodeList

class zope.structuredtext.stdom.NamedNodeMap(data=None)

NamedNodeMap interface - Is used to represent collections of nodes that can be accessed by name. NamedNodeMaps are not maintained in any particular order.

Python extensions: can use sequence-style ‘len’, ‘getitem’, and ‘for..in’ constructs, and mapping-style ‘getitem’.

item(index)

Returns the index-th item in the map.

This is arbitrary because maps have no order.

getLength()

The length of the NodeList

getNamedItem(name)

Retrieves a node specified by name. Parameters: name Name of a node to retrieve. Return Value A Node (of any type) with the specified name, or None if the specified name did not identify any node in the map.

class zope.structuredtext.stdom.Attr(name, value, specified=1)

Attr interface - The Attr interface represents an attriubte in an Element object. Attr objects inherit the Node Interface

getNodeName()

The name of this node, depending on its type

getName()

The name of this node, depending on its type

getNodeValue()

The value of this node, depending on its type

getSpecified()

If this attribute was explicitly given a value in the original document, this is true; otherwise, it is false.

zope.structuredtext.html

HTML renderer for STX documents.

zope.structuredtext.docbook

Render STX document as docbook.

class zope.structuredtext.docbook.DocBook

Structured text document renderer for Docbook.

class zope.structuredtext.docbook.DocBookChapter

class zope.structuredtext.docbook.DocBookChapterWithFigures

class zope.structuredtext.docbook.DocBookArticle

zope.structuredtext

Zope structured text markeup

Consider the following example:

>>> from zope.structuredtext.stng import structurize
>>> from zope.structuredtext.document import DocumentWithImages
>>> from zope.structuredtext.html import HTMLWithImages
>>> from zope.structuredtext.docbook import DocBook
>>> from zope.structuredtext.docbook import DocBookChapterWithFigures
>>> from zope.structuredtext.docbook import DocBookArticle

We first need to structurize the string and make a full-blown document out of it:

>>> structured_string = '''
... Title Here
...
...     Body text here.'''
>>> struct = structurize(structured_string)
>>> doc = DocumentWithImages()(struct)

Now feed it to some output generator, in this case HTML or DocBook:

>>> HTMLWithImages()(doc, level=1)
'<html>...'
>>> DocBook()(doc, level=1)
'<!DOCTYPE book ...<book>...'
>>> DocBookArticle()(doc, level=1)
'<!DOCTYPE article ...<article>...'
>>> DocBookChapterWithFigures()(doc, level=1)
'<chapter>...'

For HTML, there is a shortcut:

>>> from zope.structuredtext import stx2html
>>> stx2html(structured_string)
'<html>...'

If we have references in the text we can use a different function:

>>> from zope.structuredtext import stx2htmlWithReferences
>>> stx2htmlWithReferences(structured_string)
'<html>...'

zope.structuredtext.stx2html(aStructuredString, level=1, header=1)

A shortcut to produce HTML.

zope.structuredtext.stx2htmlWithReferences(text, level=1, header=1)

A shortcut to produce HTML with references