i2.doc_mint

Meta-interfaces

Functions

convert_string(s, converters)

Convert s with the first converter that matches (a dict containing s as a key, or a callable returning something other than None); return s if none does.

detect_doc_style(docstring)

Detect which parameter-description style a docstring uses, or None.

docstring_to_params(docstring, *[, ...])

Parse a docstring and extract parameter specifications.

find_in_params(query, params, *[, search_in])

Find parameters in a list of parameter specifications.

indent_lines(string, indent)

Indent each line of a string.

inject_docstring_content(to_inject, *[, ...])

Inject content into the docstring of a function.

literal_eval_converter(s[, max_length])

Evaluate s as a Python literal, or return None when it is not one (or is longer than max_length, or contains a newline or ;).

most_common_indent(string[, ignore_first_line])

Find the most common indentation in a string.

params_to_docstring(params, *[, doc_style, ...])

Generate a docstring from a list of parameter specifications.

register_converter(converter)

Register a new converter.

string_param_to_obj(string_to_object_mapping)

Convert a string representation of a parameter to an object.

i2.doc_mint.convert_string(s, converters)[source]

Convert s with the first converter that matches (a dict containing s as a key, or a callable returning something other than None); return s if none does.

>>> convert_string("None", dflt_str_to_obj_converters), convert_string("3.5", dflt_str_to_obj_converters)
(None, 3.5)
>>> convert_string("hello", dflt_str_to_obj_converters)
'hello'
Return type:

object

i2.doc_mint.detect_doc_style(docstring)[source]

Detect which parameter-description style a docstring uses, or None.

Returns 'numpy', 'rest' or 'google' (the styles docstring_to_params and params_to_docstring handle), based on each style’s section markers. A callable’s __doc__ is used.

>>> detect_doc_style('''
... Parameters
... ----------
... x : int
...     An integer.
... ''')
'numpy'
>>> detect_doc_style('''
... Args:
...     x (int): An integer.
... ''')
'google'
>>> detect_doc_style('''
... :param x: An integer.
... :type x: int
... ''')
'rest'

When several styles’ markers appear (e.g. a google docstring whose example shows reST fields), the one that comes first wins:

>>> detect_doc_style('''
... Args:
...     x (int): An integer.
...
... Example:
...     :param y: shown as text, not a field.
... ''')
'google'
>>> detect_doc_style('Just a summary line.') is None
True
>>> detect_doc_style(None) is None
True

It reads the markers of the docstring as written, so it works on the indented __doc__ of a function too:

>>> def f(x):
...     '''Do it.
...
...     :param x: An integer.
...     '''
>>> detect_doc_style(f)
'rest'
Return type:

Optional[Literal['numpy', 'google', 'rest']]

i2.doc_mint.docstring_to_params(docstring, *, doc_style='numpy', converters=[{'-inf': -inf, 'False': False, 'None': None, 'True': True, 'bool': <class 'bool'>, 'complex': <class 'complex'>, 'dict': <class 'dict'>, 'float': <class 'float'>, 'inf': inf, 'int': <class 'int'>, 'list': <class 'list'>, 'nan': nan, 'set': <class 'set'>, 'str': <class 'str'>, 'tuple': <class 'tuple'>}, <function literal_eval_converter>])[source]

Parse a docstring and extract parameter specifications.

Parameters:
  • docstring (str) – The docstring to parse.

  • doc_style (Literal['numpy', 'google', 'rest', 'auto']) – The style of the docstring to parse. One of ‘numpy’, ‘google’, or ‘rest’, or ‘auto’ to use the style detect_doc_style finds (falling back to ‘numpy’).

Return type:

list[dict]

Returns:

A list of parameter specifications, where each specification is a dictionary containing:

  • name: The name of the parameter (str).

  • default: The default value of the parameter (str, optional).

  • annotation: The type annotation for the parameter (str, optional).

  • description: A description of the parameter (str).

Examples

>>> docstring = '''
... Parameters
... ----------
... x : int, default=1
...     An integer value.
... y : str, default=None
...     An optional string.
... '''
>>> params = docstring_to_params(docstring)
>>> params  == [
...     {'name': 'x', 'default': 1, 'annotation': int, 'description': 'An integer value.'},
...     {'name': 'y', 'default': None, 'annotation': str, 'description': 'An optional string.'}
... ]
True
>>> docstring = '''
... Args:
...     x (int, optional): An integer value. Defaults to 1.
...     y (str, optional): An optional string. Defaults to None.
... '''
>>> params = docstring_to_params(docstring, doc_style='google')
>>> params == [
...     {"name": "x", "default": 1, "annotation": int, "description": "An integer value."},
...     {"name": "y", "default": None, "annotation": str, "description": "An optional string."},
... ]
True
>>> docstring = '''
... :param x: An integer value. (Default: 1)
... :type x: int
... :param y: An optional string. (Default: None)
... :type y: str
... '''
>>> params = docstring_to_params(docstring, doc_style='rest')
>>> params == [
...     {"name": "x", "default": 1, "annotation": int, "description": "An integer value."},
...     {"name": "y", "default": None, "annotation": str, "description": "An optional string."},
... ]
True

With doc_style='auto', the style is detected (see detect_doc_style). A function’s (indented) __doc__ works too:

>>> docstring_to_params(docstring, doc_style='auto') == params
True
>>> def f(x=1):
...     '''Do it.
...
...     Args:
...         x (int, optional): An integer value. Defaults to 1.
...     '''
>>> [p['name'] for p in docstring_to_params(f, doc_style='auto')]
['x']

The Sphinx typed-field form (:param int x:) and CRLF line endings are handled:

>>> docstring_to_params(':param int x: X.\r\n:param y: Note: Y.', doc_style='auto') == [
...     {"name": "x", "default": None, "annotation": int, "description": "X."},
...     {"name": "y", "default": None, "annotation": None, "description": "Note: Y."},
... ]
True
i2.doc_mint.find_in_params(query, params, *, search_in=('name', 'description'))[source]

Find parameters in a list of parameter specifications.

Parameters:
  • query (str) – The query to search for.

  • params (Callable | str) –

    The list of parameter specifications. Params can be provided in two formats:

    • A function, from which the params will be extracted from the docstring.

    • A list of dictionaries where each dictionary specifies a parameter, containing:

      • name: The name of the parameter (str).

      • default: The default value of the parameter (any, optional).

      • annotation: The type annotation for the parameter (str, optional).

      • description: A description of the parameter (str).

    If a callable is provided, it will be used to generate the list of parameter specifications.

  • search_in – The fields to search in each parameter specification.

Return type:

list[dict]

Returns:

A list of parameter specifications that match the query.

Examples

>>> params = [
...     {"name": "x", "default": 1, "annotation": "int", "description": "An integer value."},
...     {"name": "y", "default": None, "annotation": "str", "description": "An optional string."},
... ]
>>> find_in_params('int', params)
[{'name': 'x', 'default': 1, 'annotation': 'int', 'description': 'An integer value.'}]
i2.doc_mint.indent_lines(string, indent)[source]

Indent each line of a string.

Parameters:
  • string (str) – The string to indent.

  • indent (str) – The string to use for indentation.

Return type:

str

Returns:

The indented string.

Examples

>>> print(indent_lines('This is a test.\nAnother line.', ' ' * 8))
        This is a test.
        Another line.
i2.doc_mint.inject_docstring_content(to_inject, *, position=-1, indent=True)[source]

Inject content into the docstring of a function.

Note

If you use the decorator on a string, it will assume that string is the doc string you want to transform and return the modified string directly.

Parameters:
  • to_inject – The content to inject.

  • position – The position in the docstring to inject the content. If an integer, the content is injected at that line number (pushing the rest down). If a string, will consider it as a regex pattern to match the line to inject after. Default is -1, to inject at the end.

  • indent – Control on indent. If True, will use the most common indent of the input docstrings. If a string, it will use that specific string.

Returns:

A decorator that injects the content into the docstring of the decorated function.

Examples

>>> @inject_docstring_content('This is a test.')
... def test_func():
...     '''This is the docstring.'''
...     pass
>>> test_func.__doc__
'This is the docstring.\nThis is a test.'
>>> @inject_docstring_content('This is a test.', position='###INSERT HERE###')
... def test_func():
...     '''This is the docstring.
...     ###INSERT HERE###
...     More blah.
...     '''
...     pass
>>> test_func.__doc__
'This is the docstring.\n    ###INSERT HERE###\n    More blah.\n    '
i2.doc_mint.literal_eval_converter(s, max_length=1000)[source]

Evaluate s as a Python literal, or return None when it is not one (or is longer than max_length, or contains a newline or ;).

>>> literal_eval_converter("[1, 2]"), literal_eval_converter("foo")
([1, 2], None)
i2.doc_mint.most_common_indent(string, ignore_first_line=True)[source]

Find the most common indentation in a string.

Parameters:
  • string (str) – The string to analyze.

  • ignore_first_line – Whether to ignore the first line when determining the indentation. Default is True since the first line often has no indentation because of the way python strings appear in code.

Return type:

str

Returns:

The most common indentation string.

Examples

>>> most_common_indent('    This is a test.\n    Another line.')
'    '
i2.doc_mint.params_to_docstring(params, *, doc_style='numpy', take_name_of_types=False, quote_string_defaults=True)[source]

Generate a docstring from a list of parameter specifications.

Parameters:
  • params (list[dict]) –

    A list of dictionaries where each dictionary specifies a parameter. Each dictionary should contain:

    • name: The name of the parameter (str).

    • default: The default value of the parameter (any, optional).

    • annotation: The type annotation for the parameter (str, optional).

    • description: A description of the parameter (str).

  • doc_style (str) – The style of the docstring to generate. One of ‘numpy’, ‘google’, or ‘rest’.

  • take_name_of_types (bool) – Whether to use the name of the type as the annotation (bool).

  • quote_string_defaults (bool) – Whether to quote string defaults (bool).

Return type:

str

Returns:

A formatted docstring (str).

Examples

>>> params = [
...     {"name": "x", "default": 1, "annotation": "int", "description": "An integer value."},
...     {"name": "y", "default": None, "annotation": "str", "description": "An optional string."},
... ]
>>> print(params_to_docstring(params))
:param x: An integer value.
:type x: int, default=1
:param y: An optional string.
:type y: str, default=None
:param <BLANKLINE>:
:param >>> print(params_to_docstring(params:
:type >>> print(params_to_docstring(params: +NORMALIZE_WHITESPACE
:param doc_style='google'))  # doctest:
:type doc_style='google'))
:param Args: x (int, optional): An integer value. Defaults to 1.
             y (str, optional): An optional string. Defaults to None.
:param <BLANKLINE>:
:param >>> print(params_to_docstring(params:
:type >>> print(params_to_docstring(params: +NORMALIZE_WHITESPACE
:param doc_style='rest'))  # doctest:
:type doc_style='rest'))
:param :
:type : param x: An integer value. (Default: 1)
:param :
:type : type x: int
:param :
:type : param y: An optional string. (Default: None)
:param :
:type : type y: str
:param <BLANKLINE>:
i2.doc_mint.register_converter(converter)[source]

Register a new converter. A converter can be:

  • A dict: { “None”: None, “int”: int, … }

  • A callable: lambda s: attempt to parse s and return object or None

i2.doc_mint.string_param_to_obj(string_to_object_mapping, string=None)[source]

Convert a string representation of a parameter to an object.

Use Case: When parsing a docstring, you get values as strings, but these values may need to be converted to their actual object types (in the case of default and annotatios for example). This is a helper function to do that conversion.

Parameters:
  • string – The string representation of the parameter.

  • string_to_object_mapping (dict) – A mapping from string representations to objects.

Returns:

The object corresponding to the string representation.

Examples

>>> string_to_object_mapping = {
...     'None': None,
...     'list': list,
...     'int': int,
... }
>>> string_to_obj = string_param_to_obj(string_to_object_mapping)
>>> string_to_obj('None')
>>> string_to_obj('list')
<class 'list'>
>>> string_to_obj('int')
<class 'int'>
>>> string_to_obj('not something listed')
'not something listed'