Source code for sectiondoc.items.or_definition_item

import re

from sectiondoc.items.regex import header_regex
from sectiondoc.items.item import Item
from sectiondoc.util import trim_indent


definition_regex = re.compile(r"""
\*{0,2}            #  no, one or two stars
\w+\s:             #  a word followed by a space and a semicolumn
(
        \s         # just a space
    |              # OR
        \s[\w.]+   # dot separated words
        (\(.*\))?  # with maybe a signature
    |              # OR
        \s[\w.]+   # dot separated words
        (\(.*\))?
        \sor       # with an or in between
        \s[\w.]+
        (\(.*\))?
)?
$                  # match at the end of the line
""", re.VERBOSE)


[docs]class OrDefinitionItem(Item): """ A docstring definition section item. In this section definition item there are two classifiers that are separated by ``or``. Syntax diagram:: +-------------------------------------------------+ | term [ " : " classifier [ " or " classifier] ] | +--+----------------------------------------------+---+ | definition | | (body elements)+ | +--------------------------------------------------+ Attributes ---------- term : str The term usually reflects the name of a parameter or an attribute. classifiers : list The classifiers of the definition. Commonly used to reflect the type of an argument or the signature of a function. Only two classifiers are accepted. definition : list The list of strings that holds the description the definition item. .. note:: An Or Definition item is based on the item of a section definition list as it defined in restructured text (_http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections). """ @classmethod
[docs] def is_item(cls, line): """ Check if the line is describing a definition item. The method is used to check that a line is following the expected format for the term and classifier attributes. The expected format is:: +-------------------------------------------------+ | term [ " : " classifier [ " or " classifier] ] | +-------------------------------------------------+ Subclasses can restrict or expand this format. """ return definition_regex.match(line) is not None
@classmethod
[docs] def parse(cls, lines): """Parse a definition item from a set of lines. The class method parses the definition list item from the list of docstring lines and produces a DefinitionItem with the term, classifier and the definition. .. note:: The global indention in the definition lines is striped The term definition is assumed to be in one of the following formats:: term Definition. :: term Definition, paragraph 1. Definition, paragraph 2. :: term : classifier Definition. :: term : classifier or classifier Definition. Arguments --------- lines docstring lines of the definition without any empty lines before or after. Returns ------- definition : OrDefinitionItem """ header = lines[0].strip() term, classifiers = header_regex.split( header, maxsplit=1) if (' :' in header) else (header, '') classifiers = [ classifier.strip() for classifier in classifiers.split('or')] if classifiers == ['']: classifiers = [] trimed_lines = trim_indent(lines[1:]) if (len(lines) > 1) else [''] definition = [line.rstrip() for line in trimed_lines] return Item(term.strip(), classifiers, definition)