moldesign.utils.docparsers package¶

Submodules¶

moldesign.utils.docparsers.google module¶

Routines for runtime docstring argument injection

This file contains HEAVILY modified routines from sphinx.ext.napoleon, from version 1.4.4

This has been vendored into MDT because the modification makes use of private functions which have already changed in the dev branch.

class moldesign.utils.docparsers.google.GoogleDocArgumentInjector(docstring, prepare=True)[source]¶

Bases: object

SECTIONS = set(['args', 'arguments', 'parameters'])¶

lines()[source]¶

Return the parsed lines of the docstring in reStructuredText format.

Returns:	The lines of the docstring in a list.
Return type:	`list` of `str`

new_docstring()[source]¶

Create a new docstring with the current state of the argument list

Returns:	docstring with modified argument list
Return type:	str

parse()[source]¶: This method is a modified version of GoogleDocstring._parse

class moldesign.utils.docparsers.google.modify_iter(*args, **kwargs)[source]¶

Bases: moldesign.utils.docparsers.google.peek_iter

An iterator object that supports modifying items as they are returned. :param o: o is interpreted very differently depending on the presence of

sentinel. If sentinel is not given, then o must be a collection object which supports either the iteration protocol or the sequence protocol. If sentinel is given, then o must be a callable object.

Parameters:

sentinel (any value, optional) – If given, the iterator will call o with no arguments for each call to its next method; if the value returned is equal to sentinel, StopIteration will be raised, otherwise the value will be returned.
modifier (callable, optional) – The function that will be used to modify each item returned by the iterator. modifier should take a single argument and return a single value. Defaults to lambda x: x. If sentinel is not given, modifier must be passed as a keyword argument.

modifier¶: callable – modifier is called with each item in o as it is iterated. The return value of modifier is returned in lieu of the item. Values returned by peek as well as next are affected by modifier. However, modify_iter.sentinel is never passed through modifier; it will always be returned from peek unmodified.

Example

>>> a = ["     A list    ",
...      "   of strings  ",
...      "      with     ",
...      "      extra    ",
...      "   whitespace. "]
>>> modifier = lambda s: s.strip().replace('with', 'without')
>>> for s in modify_iter(a, modifier=modifier):
...   print('"%s"' % s)
"A list"
"of strings"
"without"
"extra"
"whitespace."

class moldesign.utils.docparsers.google.peek_iter(*args)[source]¶

Bases: object

An iterator object that supports peeking ahead. :param o: o is interpreted very differently depending on the presence of

sentinel. If sentinel is not given, then o must be a collection object which supports either the iteration protocol or the sequence protocol. If sentinel is given, then o must be a callable object.

Parameters:	sentinel (any value, optional) – If given, the iterator will call o with no arguments for each call to its next method; if the value returned is equal to sentinel, `StopIteration` will be raised, otherwise the value will be returned.

See also

peek_iter can operate as a drop in replacement for the built-in iter function.

sentinel¶: The value used to indicate the iterator is exhausted. If sentinel was not given when the peek_iter was instantiated, then it will be set to a new object instance: object().

has_next()[source]¶: Determine if iterator is exhausted. :returns: True if iterator has more items, False otherwise. :rtype: bool

Note

Will never raise StopIteration.

next(n=None)[source]¶

Get the next item or n items of the iterator. :param n: The number of items to retrieve. Defaults to None. :type n: int or None

Returns:	The next item or n items of the iterator. If n is None, the item itself is returned. If n is an int, the items will be returned in a list. If n is 0, an empty list is returned.
Return type:	item or list of items
Raises:	`StopIteration` – Raised if the iterator is exhausted, even if n is 0.

peek(n=None)[source]¶

Preview the next item or n items of the iterator. The iterator is not advanced when peek is called. :returns: The next item or n items of the iterator. If n is None, the

item itself is returned. If n is an int, the items will be returned in a list. If n is 0, an empty list is returned. If the iterator is exhausted, peek_iter.sentinel is returned, or placed as the last item in the returned list.

Return type:	item or list of items

Note

Will never raise StopIteration.

moldesign.utils.docparsers.google.prepare_docstring(s, ignore=1)[source]¶: Convert a docstring into lines of parseable reST. Remove common leading indentation, where the indentation of a given number of lines (usually just one) is ignored. Return the docstring as a list of lines usable for inserting into a docutils ViewList (used as argument of nested_parse().) An empty line is added to act as a separator between this docstring and following content.