Source code for sectiondoc.items.any_item
import re
from sectiondoc.items.regex import definition_regex, header_regex
from sectiondoc.items.item import Item
from sectiondoc.util import trim_indent
any_item_regex = re.compile(r"""
\*{0,2} # no, one or two stars
\w+ # a word followed by
(\s:?)? # space or ` :`
(.+)? # a classifier
$ # match at the end of the line
""", re.VERBOSE)
[docs]class AnyItem(Item):
""" A docstring definition section item.
In this section item the are not restrictions on the classifier's
section of the item header.
Syntax diagram::
+-------------------------------------------------+
| term [ " : " text ] |
+--+----------------------------------------------+---+
| 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. Any text after the
` : ` till the end of the line is consider a single classifier.
definition : list
The list of strings that holds the description the definition item.
.. note::
AnyItem is probably closer to numpydoc on describing a section item.
"""
@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 [ " : " text ] |
+-------------------------------------------------+
Subclasses can restrict or expand this format.
"""
return any_item_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.
::
term
Definition, paragraph 1.
Definition, paragraph 2.
::
term:
Definition, paragraph 1.
Definition, paragraph 2.
::
term : any text is valid here
Definition.
Arguments
---------
lines
docstring lines of the definition without any empty lines before or
after.
Returns
-------
definition : AnyItem
"""
header = lines[0].strip()
term, classifier = header_regex.split(header, maxsplit=1) if \
(' :' in header) else (header, '')
classifier = classifier.strip()
classifier = [] if classifier == '' else [classifier]
trimed_lines = trim_indent(lines[1:]) if (len(lines) > 1) else []
definition = [line.rstrip() for line in trimed_lines]
return cls(term.strip(), classifier, definition)