i2.doc_mint¶
Meta-interfaces
Functions
|
Convert |
|
Detect which parameter-description style a docstring uses, or |
|
Parse a docstring and extract parameter specifications. |
|
Find parameters in a list of parameter specifications. |
|
Indent each line of a string. |
|
Inject content into the docstring of a function. |
|
Evaluate |
|
Find the most common indentation in a string. |
|
Generate a docstring from a list of parameter specifications. |
|
Register a new converter. |
|
Convert a string representation of a parameter to an object. |
- i2.doc_mint.convert_string(s, converters)[source]¶
Convert
swith the first converter that matches (a dict containingsas a key, or a callable returning something other than None); returnsif 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:
- i2.doc_mint.detect_doc_style(docstring)[source]¶
Detect which parameter-description style a docstring uses, or
None.Returns
'numpy','rest'or'google'(the stylesdocstring_to_paramsandparams_to_docstringhandle), 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 TrueIt 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'
- 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:
- Return type:
- 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."}, ... ] TrueWith
doc_style='auto', the style is detected (seedetect_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.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:
- 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:
- Return type:
- 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
sas a Python literal, or return None when it is not one (or is longer thanmax_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:
- 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:
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:
- 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'