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

color_text(text, types=None)

Search the paragraph for each special structure

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

SGML text is ignored and outputed as-is

parse(raw_string, text_type, type=<type '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

class zope.structuredtext.document.DocumentWithImages

Document with images

zope.structuredtext.stletters

Structured text character classes

zope.structuredtext.stng

Core document model.

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.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.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.StructuredTextDescriptionBody(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.StructuredTextDocument(subs=None, **kw)

A StructuredTextDocument holds StructuredTextParagraphs as its subparagraphs.

getChildren()

Get a Python sequence of children

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

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

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

A simple embedded image

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

Get a Python sequence of children

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.StructuredTextParagraph(src, subs=None, **kw)
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.

getChildren()

Get a Python sequence of children

class zope.structuredtext.stng.StructuredTextRow(row, kw)
class zope.structuredtext.stng.StructuredTextSGML(value, **kw)
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.StructuredTextSectionTitle(src, subs=None, **kw)

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

class zope.structuredtext.stng.StructuredTextStrong(value, **kw)
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.StructuredTextTableData(src, subs=None, **kw)
class zope.structuredtext.stng.StructuredTextTableHeader(src, subs=None, **kw)
class zope.structuredtext.stng.StructuredTextUnderline(value, **kw)
class zope.structuredtext.stng.StructuredTextXref(value, **kw)
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.indention(str, front=<built-in method match of _sre.SRE_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.structurize(paragraphs, delimiter=<_sre.SRE_Pattern object>)

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]]

zope.structuredtext.stdom

DOM implementation in StructuredText: read-only methods

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

getName()

Returns the name of this attribute.

getNodeName()

The name of this node, depending on its type

getNodeType()

A code representing the type of the node.

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.

exception zope.structuredtext.stdom.DOMException
exception zope.structuredtext.stdom.DOMStringSizeException
class zope.structuredtext.stdom.Element

Element interface

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.

getNodeName()

The name of this node, depending on its type

getNodeType()

A code representing the type of the node.

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

getTagName()

The name of the element

exception zope.structuredtext.stdom.HierarchyRequestException
exception zope.structuredtext.stdom.InUseAttributeException
exception zope.structuredtext.stdom.IndexSizeException
exception zope.structuredtext.stdom.InvalidCharacterException
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’.

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.

item(index)

Returns the index-th item in the map

exception zope.structuredtext.stdom.NoDataAllowedException
exception zope.structuredtext.stdom.NoModificationAllowedException
class zope.structuredtext.stdom.Node

Node Interface

getAttributes()

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

getChildren()

Get a Python sequence of children

getNextSibling()

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

getNodeName()

The name of this node, depending on its type

getNodeValue()

The value of this node, depending on its type

getOwnerDocument()

The Document object associated with this node, if any.

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.

hasChildNodes()

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

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.

getLength()

The length of the NodeList

item(index)

Returns the index-th item in the collection

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

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

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.

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.

exception zope.structuredtext.stdom.NotFoundException
exception zope.structuredtext.stdom.NotSupportedException
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=<type 'type'>, sts=(<type 'unicode'>, <type 'str'>))

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

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

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

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

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

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

exception zope.structuredtext.stdom.WrongDocumentException

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.DocBookArticle
class zope.structuredtext.docbook.DocBookChapter
class zope.structuredtext.docbook.DocBookChapterWithFigures

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

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

>>> struct = structurize(structured_string)
>>> doc = DocumentWithImages()(struct)

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

>>> output = HTMLWithImages()(doc, level=1)
>>> output = DocBook()(doc, level=1)