2.9.1. vacumm.sphinxext.overview – Aperçu d’un module python

Functions:

overview_strings()

setup()

Classes:

OverView columns format_attributes() format_classes() format_functions() format_list() format_ref() format_title() format() get_extra_class_attributes() get_extra_methods() get_members() indent() OverViewDirective has_content option_spec optional_arguments required_arguments run() overview

Inheritance diagram:  

digraph inheritance0635db51c7 { rankdir=TB; ratio=compress; size="6.0, 8.0"; "Body" [color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled]; "Directive" [color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled,tooltip="Base class for reStructuredText directives."]; "Element" [color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled,tooltip="`Element` is the superclass to all specific elements."]; "Node" -> "Element" [arrowsize=0.5,penwidth=1,style="setlinewidth(0.5)"]; "General" [color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled]; "Body" -> "General" [arrowsize=0.5,penwidth=1,style="setlinewidth(0.5)"]; "Node" [color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled,tooltip="Abstract base class of nodes in a document tree."]; "OverViewDirective" [URL="#vacumm.sphinxext.overview.OverViewDirective",color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled,target="_top"]; "Directive" -> "OverViewDirective" [arrowsize=0.5,penwidth=1,style="setlinewidth(0.5)"]; "overview" [URL="#vacumm.sphinxext.overview.overview",color=orange,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.6,shape=ellipse,style=filled,target="_top"]; "General" -> "overview" [arrowsize=0.5,penwidth=1,style="setlinewidth(0.5)"]; "Element" -> "overview" [arrowsize=0.5,penwidth=1,style="setlinewidth(0.5)"]; }

Sphinx directive to add an overview of a python module or class

class OverView(object, extra_attributes=[], extra_functions=[], extra_classes=[], extra_methods=[], extra_class_attributes=[], inherited=True)

Bases: object

Python object rst overview generator

Usage:

>>> import mymodule
>>> rst_text = OverView(mymodule).format()

columns = 3

format(title_overview='Overview', title_content='Content', underline='-', indent=0, columns=None)

Format overview in rst format

format_attributes(indent=0, columns=None)

Format module level attributes

format_classes(indent=0, columns=None)

Format classes

Todo

Use inspect.getclasstree() or at least inspect.classify_class_attrs() in Overview

format_functions(indent=0, columns=None)

Format functions

format_list(args, indent=0, columns=None, xindent='')

format_ref(objname, object, clsname=None)

Format a reference link to an object

format_title(title, underline, indent=0)

Format the title of the overview or content paragraphs

get_extra_class_attributes(clsname)

Get the list of extra attributes that belongs to a class

get_extra_methods(clsname)

Get the list of extra methods that belongs to a class

get_members(object, predicate=None)

Get the list of object members of a given type

classmethod indent(indent, *text, **kwargs)

class OverViewDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

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.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)

final_argument_whitespace = False

has_content = True

info(message)

option_spec = {'columns': <function positive_int at 0x7f2009071758>, 'extra-attributes': <function overview_strings at 0x7f20026ed1b8>, 'extra-class-attributes': <function overview_strings at 0x7f20026ed1b8>, 'extra-classes': <function overview_strings at 0x7f20026ed1b8>, 'extra-functions': <function overview_strings at 0x7f20026ed1b8>, 'extra-methods': <function overview_strings at 0x7f20026ed1b8>, 'inherited-members': <function unchanged at 0x7f20090711b8>, 'title-content': <function unchanged at 0x7f20090711b8>, 'title-overview': <function unchanged at 0x7f20090711b8>, 'underline': <function single_char_or_unicode at 0x7f2009071668>}

optional_arguments = 0

required_arguments = 1

run()

severe(message)

warning(message)

class overview(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

append(item)

append_attr_list(attr, values)

For each element in values, if it does not exist in self[attr], append it.

NOTE: Requires self[attr] and values to be sequence type and the former should specifically be a list.

asdom(dom=None)

Return a DOM fragment representation of this Node.

astext()

attlist()

basic_attributes = ('ids', 'classes', 'names', 'dupnames')

child_text_separator = '\n\n'

clear()

coerce_append_attr_list(attr, value)

First, convert both self[attr] and value to a non-string sequence type; if either is not already a sequence, convert it to a list of one element. Then call append_attr_list.

NOTE: self[attr] and value both must not be None.

copy()

copy_attr_coerce(attr, value, replace)

If attr is an attribute of self and either self[attr] or value is a list, convert all non-sequence values to a sequence of 1 element and then concatenate the two sequence, setting the result to self[attr]. If both self[attr] and value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_concatenate(attr, value, replace)

If attr is an attribute of self and both self[attr] and value are lists, concatenate the two sequences, setting the result to self[attr]. If either self[attr] or value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_consistent(attr, value, replace)

If replace is True or selfpattr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_convert(attr, value, replace=True)

If attr is an attribute of self, set self[attr] to [self[attr], value], otherwise set self[attr] to value.

NOTE: replace is not used by this function and is kept only for

compatibility with the other copy functions.

deepcopy()

Return a deep copy of self (also copying children).

delattr(attr)

document = None

emptytag()

endtag()

extend(item)

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

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=9223372036854775807)

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)

get_language_code(fallback='')

Return node’s language tag.

Look iteratively in self and parents for a class argument starting with language- and return the remainder of it (which should be a BCP49 language tag) or the fallback.

has_key(attr)

hasattr(attr)

index(item)

insert(index, item)

is_not_default(key)

classmethod is_not_known_attribute(attr)

Returns True if and only if the given attribute is NOT recognized by this class.

classmethod is_not_list_attribute(attr)

Returns True if and only if the given attribute is NOT one of the basic list attributes defined for all Elements.

known_attributes = ('ids', 'classes', 'names', 'dupnames', 'backrefs', 'source')

line = None

list_attributes = ('ids', 'classes', 'names', 'dupnames', 'backrefs')

local_attributes = ('backrefs',)

next_node(condition=None, include_self=False, descend=True, siblings=False, ascend=False)

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.

parent = None

pformat(indent=' ', level=0)

Return an indented pseudo-XML representation, for test purposes.

Override in subclasses.

pop(i=-1)

remove(item)

replace(old, new)

Replace one child Node with another child or children.

replace_attr(attr, value, force=True)

If self[attr] does not exist or force is True or omitted, set self[attr] to value, otherwise do nothing.

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()

source = None

starttag(quoteattr=None)

tagname = None

traverse(condition=None, include_self=True, descend=True, siblings=False, ascend=False)

Return an iterable containing

• self (if include_self is true)
• all descendants in tree traversal order (if descend is true)
• all siblings (if siblings is true) and their descendants (if also descend is true)
• the siblings of the parent (if ascend is true) and their descendants (if also descend is true), and so on

If condition is not None, the iterable contains only nodes for which condition(node) is true. If condition is a node class cls, it is equivalent to a function consisting of return isinstance(node, cls).

If ascend is true, assume siblings to be true as well.

For example, given the following tree:

<paragraph>
    <emphasis>      <--- emphasis.traverse() and
        <strong>    <--- strong.traverse() are called.
            Foo
        Bar
    <reference name="Baz" refid="baz">
        Baz

Then list(emphasis.traverse()) equals

[<emphasis>, <strong>, <#text: Foo>, <#text: Bar>]

and list(strong.traverse(ascend=True)) equals

[<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]

update_all_atts(dict_, update_fun=<function copy_attr_consistent>, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_, the two values are merged based on the value of update_fun. Generally, when replace is True, the values in self are replaced or merged with the values in dict_; otherwise, the values in self may be preserved or merged. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

NOTE: It is easier to call the update-specific methods then to pass

the update_fun method to this function.

update_all_atts_coercion(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values are both not lists and replace is True, the values in self are replaced with the values in dict_; if either of the values from self and dict_ for the given identifier are of list type, then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_concatenating(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values aren’t each lists and replace is True, the values in self are replaced with the values in dict_; if the values from self and dict_ for the given identifier are both of list type, then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_consistantly(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ and replace is True, the values in self are replaced with the values in dict_; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_convert(dict_, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

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.

overview_strings(arg)

setup(app)