firmant.du

Functions for interacting with the docutils module.

In particular this module makes creation of directives much more straightforward and simple. The meta_data_directive() produces a MetaDataDirective. This result is suitable for registering with docutils.parsers.rst.directives.register_directive().

Docutils’ processing is a multi-step process in which a module is read, parsed, transformed, and written. Each directive created with meta_data_directive() creates a MetaDataNode in the document tree created by docutils. When the custom CustomTransformReader class is used as the reader for docutils, and is passed meta_data_transform() class, these nodes that contain metadata are then removed from the document tree, and the metadata they store is added to the dictionary that the meta_data_transform() is closed around.

Functions

firmant.du._feed_reference_role_convert(attributes)

Pull the necessary data from the attributes.

firmant.du._post_reference_role_convert(attributes)

Pull the necessary data from the attributes.

firmant.du._static_reference_role_convert(attributes)

Pull the necessary data from the attributes.

firmant.du._staticrst_reference_role_convert(attributes)

Pull the necessary data from the attributes.

firmant.du._tag_reference_role_convert(attributes)

Pull the necessary data from the attributes.

firmant.du.copyright_declaration(d, content)

Interpret the content as a copyright declaration.

>>> d = dict()
>>> copyright_declaration(d, [u'foo', u'bar'])
>>> d['copyright']
u'foo\nbar'

firmant.du.generic_reference_role(regex, typ, convert, role, rawtext, text, lineno, inliner, options=None, content=None)

A generic reference role.

It is designed to be curried with a regex, the type of link, and a function to return the extension, attributes, and urltext from the groupdict of the regex.

firmant.du.list_element(d, content, attr='element_plural')

Interpret content as an element in a list.

It returns a list so that the metadata transform can append values to the list.

>>> d = dict()
>>> list_element(d, [u'foo'])
>>> d['element_plural']
[u'foo']

The key in which to store the values may be specified.

>>> d = dict()
>>> list_element(d, [u'foo'], 'attr')
>>> d['attr']
[u'foo']

firmant.du.meta_data_directive(func, whitespace=False)

Create a Directive class to store data to a MetaDataNode.

The function func is passed the contents of the node and a dictionary into which it should place all relevant metadata it extracts from the contents.

firmant.du.meta_data_transform(data)

Create a docutils Transform that is a closure around the data dict.

firmant.du.publish(path, transforms=None)

Publish the rst document that resides at path on the filesystem.

This function returns a docutils.core.Publisher object. The optional transforms attribute may be passed with a list of transform classes that will be passed to the reader.

firmant.du.single_line(d, content, attr='line')

Interpret the content as a single line.

A single line of content passed to this function will be stored as line in the dictionary d.

>>> d = dict()
>>> single_line(d, [u'foobar'])
>>> d['line']
u'foobar'

Optionally, the attribute may be specified so that multiple single_line directives can co-exist.

>>> d = dict()
>>> single_line(d, [u'foobar'], 'attr')
>>> d['attr']
u'foobar'

firmant.du.strptime(date_string, formats)

Cast the date_string to the first format to match.

Each format string provided by formats is considered. The first format to match date_string will be used to determine the datetime.

>>> strptime('2009-02-01 11:51:15', ['%Y-%m-%d %H:%M:%S'])
datetime.datetime(2009, 2, 1, 11, 51, 15)
>>> strptime('11:51:15', ['%Y-%m-%d', '%H:%M:%S'])
datetime.datetime(1900, 1, 1, 11, 51, 15)

If the time does not match, a value error will be raised.

>>> strptime('AB:CD:EF', ['%H:%M:%S'])
Traceback (most recent call last):
ValueError: time data 'AB:CD:EF' does not match any format.

firmant.du.time(d, content)

Interpret the content as a time.

There are multiple formats that are accepted.

Using just hours:

>>> d = dict()
>>> time(d, ['15'])
>>> d['time']
datetime.time(15, 0)

Using hours and minutes:

>>> d = dict()
>>> time(d, ['15:43'])
>>> d['time']
datetime.time(15, 43)

Using hours, minutes, and seconds:

>>> d = dict()
>>> time(d, ['15:43:42'])
>>> d['time']
datetime.time(15, 43, 42)

ValueError is raised on invalid time:

>>> d = dict()
>>> time(d, ['154342'])
Traceback (most recent call last):
ValueError: time data '154342' does not match any format.

firmant.du.updated(d, content)

Interpret content as a full datetime.

There are multiple formats that are accepted.

YYYY-MM-DD HH:MM:SS (time may be omitted):

>>> d = dict()
>>> updated(d, ['2009-02-01 14:15:51'])
>>> d['updated']
datetime.datetime(2009, 2, 1, 14, 15, 51)

>>> updated(d, ['2009-02-01'])
>>> d['updated']
datetime.datetime(2009, 2, 1, 0, 0)

MM-DD-YYYY HH:MM:SS (time may be omitted):

>>> d = dict()
>>> updated(d, ['02-01-2009 14:15:51'])
>>> d['updated']
datetime.datetime(2009, 2, 1, 14, 15, 51)

>>> updated(d, ['02-01-2009'])
>>> d['updated']
datetime.datetime(2009, 2, 1, 0, 0)

ValueError is raised on invalid datetime:

>>> d = dict()
>>> updated(d, ['154342'])
Traceback (most recent call last):
ValueError: time data '154342' does not match any format.

firmant.du.url_node_transform(urlmapper)

Create a docutils Transform that is a closure around the urlmapper object.

Classes

class firmant.du.CustomTransformsReader(parser=None, parser_name=None, transforms=None)

Bases: docutils.readers.standalone.Reader

Add transformations to read MetaData from doctree.

get_transforms()

Add a transform for moving the meta data into the data dictionary.

new_document()

Create and return a new empty document tree (root node).

parse()

Parse self.input into a document tree.

read(source, parser, settings)

set_parser(parser_name)

Set self.parser by name.

supports(format)

Is format supported by this component?

To be used by transforms to ask the dependent component if it supports a certain input context or output format.

class firmant.du.Directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: object

Base class for reStructuredText directives.

The following attributes may be set by subclasses. They are interpreted by the directive parser (which runs the directive class):

• required_arguments: The number of required arguments (default: 0).

• optional_arguments: The number of optional arguments (default: 0).

• final_argument_whitespace: A boolean, indicating if the final argument may contain whitespace (default: False).

• option_spec: A dictionary, mapping known option names to conversion functions such as int or float (default: {}, no options). Several conversion functions are defined in the directives/__init__.py module.

  Option conversion functions take a single parameter, the option argument (a string or None), validate it and/or convert it to the appropriate form. Conversion functions may raise ValueError and TypeError exceptions.

• has_content: A boolean; True if content is allowed. Client code must handle the case where content is required but not supplied (an empty content list will be supplied).

Arguments are normally single whitespace-separated words. The final argument may contain whitespace and/or newlines if final_argument_whitespace is True.

If the form of the arguments is more complex, specify only one argument (either required or optional) and set final_argument_whitespace to True; the client code must do any context-sensitive parsing.

When a directive implementation is being run, the directive class is instantiated, and the run() method is executed. During instantiation, the following instance variables are set:

• name is the directive type or name (string).
• arguments is the list of positional arguments (strings).
• options is a dictionary mapping option names (strings) to values (type depends on option conversion functions; see option_spec above).
• content is a list of strings, the directive content line by line.
• lineno is the line number of the first line of the directive.
• content_offset is the line offset of the first line of the content from the beginning of the current input. Used when initiating a nested parse.
• block_text is a string containing the entire directive.
• state is the state which called the directive function.
• state_machine is the state machine which controls the state which called the directive function.

Directive functions return a list of nodes which will be inserted into the document tree at the point where the directive was encountered. This can be an empty list if there is nothing to insert.

For ordinary directives, the list must contain body elements or structural elements. Some directives are intended specifically for substitution definitions, and must return a list of Text nodes and/or inline elements (suitable for inline insertion, in place of the substitution reference). Such directives must verify substitution definition context, typically using code like this:

if not isinstance(state, states.SubstitutionDef):
    error = state_machine.reporter.error(
        'Invalid context: the "%s" directive can only be used '
        'within a substitution definition.' % (name),
        nodes.literal_block(block_text, block_text), line=lineno)
    return [error]

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

debug(message)

directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

You’d often use self.error(message) instead, which will generate an ERROR-level directive error.

error(message)

final_argument_whitespace

May the final argument contain whitespace?

has_content

May the directive have content?

info(message)

option_spec

Mapping of option names to validator functions.

optional_arguments

Number of optional arguments after the required arguments.

required_arguments

Number of required directive arguments.

run()

severe(message)

warning(message)

class firmant.du.MetaDataNode(details=None, rawsource='', *children, **attributes)

Bases: docutils.nodes.Element, docutils.nodes.Invisible, docutils.nodes.Special

The MetaDataNode is a node that holds metadata for later Transforms.

append(item)

asdom(dom=None)

Return a DOM fragment representation of this Node.

astext()

attlist()

clear()

copy()

deepcopy()

delattr(attr)

emptytag()

endtag()

extend(item)

first_child_matching_class(childclass, start=0, end=2147483647)

Return the index of the first child whose class exactly matches.

Parameters:

• childclass: A Node subclass to search for, or a tuple of Node classes. If a tuple, any of the classes may match.
• start: Initial index to check.
• end: Initial index to not check.

first_child_not_matching_class(childclass, start=0, end=2147483647)

Return the index of the first child whose class does not match.

Parameters:

• childclass: A Node subclass to skip, or a tuple of Node classes. If a tuple, none of the classes may match.
• start: Initial index to check.
• end: Initial index to not check.

get(key, failobj=None)

has_key(attr)

hasattr(attr)

index(item)

insert(index, item)

is_not_default(key)

next_node(condition=None, include_self=0, descend=1, siblings=0, ascend=0)

Return the first node in the iterable returned by traverse(), or None if the iterable is empty.

Parameter list is the same as of traverse. Note that include_self defaults to 0, though.

non_default_attributes()

note_referenced_by(name=None, id=None)

Note that this Element has been referenced by its name name or id id.

pformat(indent=' ', level=0)

pop(i=-1)

remove(item)

replace(old, new)

Replace one child Node with another child or children.

replace_self(new)

Replace self node with new, where new is a node or a list of nodes.

set_class(name)

Add a new class to the “classes” attribute.

setdefault(key, failobj=None)

setup_child(child)

shortrepr()

starttag()

traverse(condition=None, include_self=1, descend=1, siblings=0, ascend=0)

update_basic_atts(dict)

Update basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) from node or dictionary dict.

walk(visitor)

Traverse a tree of Node objects, calling the dispatch_visit() method of visitor when entering each node. (The walkabout() method is similar, except it also calls the dispatch_departure() method before exiting each node.)

This tree traversal supports limited in-place tree modifications. Replacing one node with one or more nodes is OK, as is removing an element. However, if the node removed or replaced occurs after the current node, the old node will still be traversed, and any new nodes will not.

Within visit methods (and depart methods for walkabout()), TreePruningException subclasses may be raised (SkipChildren, SkipSiblings, SkipNode, SkipDeparture).

Parameter visitor: A NodeVisitor object, containing a visit implementation for each Node subclass encountered.

Return true if we should stop the traversal.

walkabout(visitor)

Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.

Parameter visitor: A NodeVisitor object, containing a visit and depart implementation for each Node subclass encountered.

Return true if we should stop the traversal.

class firmant.du.Transform(document, startnode=None)

Docutils transform component abstract base class.

apply(**kwargs)

Override to apply the transform to the document tree.

default_priority

Numerical priority of this transform, 0 through 999 (override).

class firmant.du.URLAttributeNode(extension, urlattributes, urltext, rawsource='', *children, **attributes)

Bases: docutils.nodes.Element, docutils.nodes.Invisible, docutils.nodes.Special

The URLAttributeNode is a node that url attributes for a later transform.

append(item)

asdom(dom=None)

Return a DOM fragment representation of this Node.

astext()

attlist()

clear()

copy()

deepcopy()

delattr(attr)

emptytag()

endtag()

extend(item)

first_child_matching_class(childclass, start=0, end=2147483647)

Return the index of the first child whose class exactly matches.

Parameters:

• childclass: A Node subclass to search for, or a tuple of Node classes. If a tuple, any of the classes may match.
• start: Initial index to check.
• end: Initial index to not check.

first_child_not_matching_class(childclass, start=0, end=2147483647)

Return the index of the first child whose class does not match.

Parameters:

• childclass: A Node subclass to skip, or a tuple of Node classes. If a tuple, none of the classes may match.
• start: Initial index to check.
• end: Initial index to not check.

get(key, failobj=None)

has_key(attr)

hasattr(attr)

index(item)

insert(index, item)

is_not_default(key)

next_node(condition=None, include_self=0, descend=1, siblings=0, ascend=0)

Return the first node in the iterable returned by traverse(), or None if the iterable is empty.

Parameter list is the same as of traverse. Note that include_self defaults to 0, though.

non_default_attributes()

note_referenced_by(name=None, id=None)

Note that this Element has been referenced by its name name or id id.

pformat(indent=' ', level=0)

pop(i=-1)

remove(item)

replace(old, new)

Replace one child Node with another child or children.

replace_self(new)

Replace self node with new, where new is a node or a list of nodes.

set_class(name)

Add a new class to the “classes” attribute.

setdefault(key, failobj=None)

setup_child(child)

shortrepr()

starttag()

traverse(condition=None, include_self=1, descend=1, siblings=0, ascend=0)

update_basic_atts(dict)

Update basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) from node or dictionary dict.

walk(visitor)

Traverse a tree of Node objects, calling the dispatch_visit() method of visitor when entering each node. (The walkabout() method is similar, except it also calls the dispatch_departure() method before exiting each node.)

This tree traversal supports limited in-place tree modifications. Replacing one node with one or more nodes is OK, as is removing an element. However, if the node removed or replaced occurs after the current node, the old node will still be traversed, and any new nodes will not.

Within visit methods (and depart methods for walkabout()), TreePruningException subclasses may be raised (SkipChildren, SkipSiblings, SkipNode, SkipDeparture).

Parameter visitor: A NodeVisitor object, containing a visit implementation for each Node subclass encountered.

Return true if we should stop the traversal.

walkabout(visitor)

Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.

Parameter visitor: A NodeVisitor object, containing a visit and depart implementation for each Node subclass encountered.

Return true if we should stop the traversal.