Tipragot
628be439b8
Cela permet de ne pas avoir de problèmes de compatibilité car python est dans le git.
947 lines
29 KiB
Python
947 lines
29 KiB
Python
# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
|
|
# For details: https://github.com/pylint-dev/pylint/blob/main/LICENSE
|
|
# Copyright (c) https://github.com/pylint-dev/pylint/blob/main/CONTRIBUTORS.txt
|
|
|
|
"""Utility methods for docstring checking."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import itertools
|
|
import re
|
|
from collections.abc import Iterable
|
|
|
|
import astroid
|
|
from astroid import nodes
|
|
from astroid.util import UninferableBase
|
|
|
|
from pylint.checkers import utils
|
|
|
|
|
|
def space_indentation(s: str) -> int:
|
|
"""The number of leading spaces in a string.
|
|
|
|
:param str s: input string
|
|
|
|
:rtype: int
|
|
:return: number of leading spaces
|
|
"""
|
|
return len(s) - len(s.lstrip(" "))
|
|
|
|
|
|
def get_setters_property_name(node: nodes.FunctionDef) -> str | None:
|
|
"""Get the name of the property that the given node is a setter for.
|
|
|
|
:param node: The node to get the property name for.
|
|
:type node: str
|
|
|
|
:rtype: str or None
|
|
:returns: The name of the property that the node is a setter for,
|
|
or None if one could not be found.
|
|
"""
|
|
decorators = node.decorators.nodes if node.decorators else []
|
|
for decorator in decorators:
|
|
if (
|
|
isinstance(decorator, nodes.Attribute)
|
|
and decorator.attrname == "setter"
|
|
and isinstance(decorator.expr, nodes.Name)
|
|
):
|
|
return decorator.expr.name # type: ignore[no-any-return]
|
|
return None
|
|
|
|
|
|
def get_setters_property(node: nodes.FunctionDef) -> nodes.FunctionDef | None:
|
|
"""Get the property node for the given setter node.
|
|
|
|
:param node: The node to get the property for.
|
|
:type node: nodes.FunctionDef
|
|
|
|
:rtype: nodes.FunctionDef or None
|
|
:returns: The node relating to the property of the given setter node,
|
|
or None if one could not be found.
|
|
"""
|
|
property_ = None
|
|
|
|
property_name = get_setters_property_name(node)
|
|
class_node = utils.node_frame_class(node)
|
|
if property_name and class_node:
|
|
class_attrs: list[nodes.FunctionDef] = class_node.getattr(node.name)
|
|
for attr in class_attrs:
|
|
if utils.decorated_with_property(attr):
|
|
property_ = attr
|
|
break
|
|
|
|
return property_
|
|
|
|
|
|
def returns_something(return_node: nodes.Return) -> bool:
|
|
"""Check if a return node returns a value other than None.
|
|
|
|
:param return_node: The return node to check.
|
|
:type return_node: astroid.Return
|
|
|
|
:rtype: bool
|
|
:return: True if the return node returns a value other than None,
|
|
False otherwise.
|
|
"""
|
|
returns = return_node.value
|
|
|
|
if returns is None:
|
|
return False
|
|
|
|
return not (isinstance(returns, nodes.Const) and returns.value is None)
|
|
|
|
|
|
def _get_raise_target(node: nodes.NodeNG) -> nodes.NodeNG | UninferableBase | None:
|
|
if isinstance(node.exc, nodes.Call):
|
|
func = node.exc.func
|
|
if isinstance(func, (nodes.Name, nodes.Attribute)):
|
|
return utils.safe_infer(func)
|
|
return None
|
|
|
|
|
|
def _split_multiple_exc_types(target: str) -> list[str]:
|
|
delimiters = r"(\s*,(?:\s*or\s)?\s*|\s+or\s+)"
|
|
return re.split(delimiters, target)
|
|
|
|
|
|
def possible_exc_types(node: nodes.NodeNG) -> set[nodes.ClassDef]:
|
|
"""Gets all the possible raised exception types for the given raise node.
|
|
|
|
.. note::
|
|
|
|
Caught exception types are ignored.
|
|
|
|
:param node: The raise node to find exception types for.
|
|
|
|
:returns: A list of exception types possibly raised by :param:`node`.
|
|
"""
|
|
exceptions = []
|
|
if isinstance(node.exc, nodes.Name):
|
|
inferred = utils.safe_infer(node.exc)
|
|
if inferred:
|
|
exceptions = [inferred]
|
|
elif node.exc is None:
|
|
handler = node.parent
|
|
while handler and not isinstance(handler, nodes.ExceptHandler):
|
|
handler = handler.parent
|
|
|
|
if handler and handler.type:
|
|
try:
|
|
for exception in astroid.unpack_infer(handler.type):
|
|
if not isinstance(exception, UninferableBase):
|
|
exceptions.append(exception)
|
|
except astroid.InferenceError:
|
|
pass
|
|
else:
|
|
target = _get_raise_target(node)
|
|
if isinstance(target, nodes.ClassDef):
|
|
exceptions = [target]
|
|
elif isinstance(target, nodes.FunctionDef):
|
|
for ret in target.nodes_of_class(nodes.Return):
|
|
if ret.value is None:
|
|
continue
|
|
if ret.frame() != target:
|
|
# return from inner function - ignore it
|
|
continue
|
|
|
|
val = utils.safe_infer(ret.value)
|
|
if val and utils.inherit_from_std_ex(val):
|
|
if isinstance(val, nodes.ClassDef):
|
|
exceptions.append(val)
|
|
elif isinstance(val, astroid.Instance):
|
|
exceptions.append(val.getattr("__class__")[0])
|
|
|
|
try:
|
|
return {
|
|
exc
|
|
for exc in exceptions
|
|
if not utils.node_ignores_exception(node, exc.name)
|
|
}
|
|
except astroid.InferenceError:
|
|
return set()
|
|
|
|
|
|
def _is_ellipsis(node: nodes.NodeNG) -> bool:
|
|
return isinstance(node, nodes.Const) and node.value == Ellipsis
|
|
|
|
|
|
def _merge_annotations(
|
|
annotations: Iterable[nodes.NodeNG], comment_annotations: Iterable[nodes.NodeNG]
|
|
) -> Iterable[nodes.NodeNG | None]:
|
|
for ann, comment_ann in itertools.zip_longest(annotations, comment_annotations):
|
|
if ann and not _is_ellipsis(ann):
|
|
yield ann
|
|
elif comment_ann and not _is_ellipsis(comment_ann):
|
|
yield comment_ann
|
|
else:
|
|
yield None
|
|
|
|
|
|
def _annotations_list(args_node: nodes.Arguments) -> list[nodes.NodeNG]:
|
|
"""Get a merged list of annotations.
|
|
|
|
The annotations can come from:
|
|
|
|
* Real type annotations.
|
|
* A type comment on the function.
|
|
* A type common on the individual argument.
|
|
|
|
:param args_node: The node to get the annotations for.
|
|
:returns: The annotations.
|
|
"""
|
|
plain_annotations = args_node.annotations or ()
|
|
func_comment_annotations = args_node.parent.type_comment_args or ()
|
|
comment_annotations = args_node.type_comment_posonlyargs
|
|
comment_annotations += args_node.type_comment_args or []
|
|
comment_annotations += args_node.type_comment_kwonlyargs
|
|
return list(
|
|
_merge_annotations(
|
|
plain_annotations,
|
|
_merge_annotations(func_comment_annotations, comment_annotations),
|
|
)
|
|
)
|
|
|
|
|
|
def args_with_annotation(args_node: nodes.Arguments) -> set[str]:
|
|
result = set()
|
|
annotations = _annotations_list(args_node)
|
|
annotation_offset = 0
|
|
|
|
if args_node.posonlyargs:
|
|
posonlyargs_annotations = args_node.posonlyargs_annotations
|
|
if not any(args_node.posonlyargs_annotations):
|
|
num_args = len(args_node.posonlyargs)
|
|
posonlyargs_annotations = annotations[
|
|
annotation_offset : annotation_offset + num_args
|
|
]
|
|
annotation_offset += num_args
|
|
|
|
for arg, annotation in zip(args_node.posonlyargs, posonlyargs_annotations):
|
|
if annotation:
|
|
result.add(arg.name)
|
|
|
|
if args_node.args:
|
|
num_args = len(args_node.args)
|
|
for arg, annotation in zip(
|
|
args_node.args,
|
|
annotations[annotation_offset : annotation_offset + num_args],
|
|
):
|
|
if annotation:
|
|
result.add(arg.name)
|
|
|
|
annotation_offset += num_args
|
|
|
|
if args_node.vararg:
|
|
if args_node.varargannotation:
|
|
result.add(args_node.vararg)
|
|
elif len(annotations) > annotation_offset and annotations[annotation_offset]:
|
|
result.add(args_node.vararg)
|
|
annotation_offset += 1
|
|
|
|
if args_node.kwonlyargs:
|
|
kwonlyargs_annotations = args_node.kwonlyargs_annotations
|
|
if not any(args_node.kwonlyargs_annotations):
|
|
num_args = len(args_node.kwonlyargs)
|
|
kwonlyargs_annotations = annotations[
|
|
annotation_offset : annotation_offset + num_args
|
|
]
|
|
annotation_offset += num_args
|
|
|
|
for arg, annotation in zip(args_node.kwonlyargs, kwonlyargs_annotations):
|
|
if annotation:
|
|
result.add(arg.name)
|
|
|
|
if args_node.kwarg:
|
|
if args_node.kwargannotation:
|
|
result.add(args_node.kwarg)
|
|
elif len(annotations) > annotation_offset and annotations[annotation_offset]:
|
|
result.add(args_node.kwarg)
|
|
annotation_offset += 1
|
|
|
|
return result
|
|
|
|
|
|
def docstringify(
|
|
docstring: nodes.Const | None, default_type: str = "default"
|
|
) -> Docstring:
|
|
best_match = (0, DOCSTRING_TYPES.get(default_type, Docstring)(docstring))
|
|
for docstring_type in (
|
|
SphinxDocstring,
|
|
EpytextDocstring,
|
|
GoogleDocstring,
|
|
NumpyDocstring,
|
|
):
|
|
instance = docstring_type(docstring)
|
|
matching_sections = instance.matching_sections()
|
|
if matching_sections > best_match[0]:
|
|
best_match = (matching_sections, instance)
|
|
|
|
return best_match[1]
|
|
|
|
|
|
class Docstring:
|
|
re_for_parameters_see = re.compile(
|
|
r"""
|
|
For\s+the\s+(other)?\s*parameters\s*,\s+see
|
|
""",
|
|
re.X | re.S,
|
|
)
|
|
|
|
supports_yields: bool = False
|
|
"""True if the docstring supports a "yield" section.
|
|
|
|
False if the docstring uses the returns section to document generators.
|
|
"""
|
|
|
|
# These methods are designed to be overridden
|
|
def __init__(self, doc: nodes.Const | None) -> None:
|
|
docstring: str = doc.value if doc else ""
|
|
self.doc = docstring.expandtabs()
|
|
|
|
def __repr__(self) -> str:
|
|
return f"<{self.__class__.__name__}:'''{self.doc}'''>"
|
|
|
|
def matching_sections(self) -> int:
|
|
"""Returns the number of matching docstring sections."""
|
|
return 0
|
|
|
|
def exceptions(self) -> set[str]:
|
|
return set()
|
|
|
|
def has_params(self) -> bool:
|
|
return False
|
|
|
|
def has_returns(self) -> bool:
|
|
return False
|
|
|
|
def has_rtype(self) -> bool:
|
|
return False
|
|
|
|
def has_property_returns(self) -> bool:
|
|
return False
|
|
|
|
def has_property_type(self) -> bool:
|
|
return False
|
|
|
|
def has_yields(self) -> bool:
|
|
return False
|
|
|
|
def has_yields_type(self) -> bool:
|
|
return False
|
|
|
|
def match_param_docs(self) -> tuple[set[str], set[str]]:
|
|
return set(), set()
|
|
|
|
def params_documented_elsewhere(self) -> bool:
|
|
return self.re_for_parameters_see.search(self.doc) is not None
|
|
|
|
|
|
class SphinxDocstring(Docstring):
|
|
re_type = r"""
|
|
[~!.]? # Optional link style prefix
|
|
\w(?:\w|\.[^\.])* # Valid python name
|
|
"""
|
|
|
|
re_simple_container_type = rf"""
|
|
{re_type} # a container type
|
|
[\(\[] [^\n\s]+ [\)\]] # with the contents of the container
|
|
"""
|
|
|
|
re_multiple_simple_type = rf"""
|
|
(?:{re_simple_container_type}|{re_type})
|
|
(?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{re_simple_container_type}|{re_type}))*
|
|
"""
|
|
|
|
re_xref = rf"""
|
|
(?::\w+:)? # optional tag
|
|
`{re_type}` # what to reference
|
|
"""
|
|
|
|
re_param_raw = rf"""
|
|
: # initial colon
|
|
(?: # Sphinx keywords
|
|
param|parameter|
|
|
arg|argument|
|
|
key|keyword
|
|
)
|
|
\s+ # whitespace
|
|
|
|
(?: # optional type declaration
|
|
({re_type}|{re_simple_container_type})
|
|
\s+
|
|
)?
|
|
|
|
((\\\*{{0,2}}\w+)|(\w+)) # Parameter name with potential asterisks
|
|
\s* # whitespace
|
|
: # final colon
|
|
"""
|
|
re_param_in_docstring = re.compile(re_param_raw, re.X | re.S)
|
|
|
|
re_type_raw = rf"""
|
|
:type # Sphinx keyword
|
|
\s+ # whitespace
|
|
({re_multiple_simple_type}) # Parameter name
|
|
\s* # whitespace
|
|
: # final colon
|
|
"""
|
|
re_type_in_docstring = re.compile(re_type_raw, re.X | re.S)
|
|
|
|
re_property_type_raw = rf"""
|
|
:type: # Sphinx keyword
|
|
\s+ # whitespace
|
|
{re_multiple_simple_type} # type declaration
|
|
"""
|
|
re_property_type_in_docstring = re.compile(re_property_type_raw, re.X | re.S)
|
|
|
|
re_raise_raw = rf"""
|
|
: # initial colon
|
|
(?: # Sphinx keyword
|
|
raises?|
|
|
except|exception
|
|
)
|
|
\s+ # whitespace
|
|
({re_multiple_simple_type}) # exception type
|
|
\s* # whitespace
|
|
: # final colon
|
|
"""
|
|
re_raise_in_docstring = re.compile(re_raise_raw, re.X | re.S)
|
|
|
|
re_rtype_in_docstring = re.compile(r":rtype:")
|
|
|
|
re_returns_in_docstring = re.compile(r":returns?:")
|
|
|
|
supports_yields = False
|
|
|
|
def matching_sections(self) -> int:
|
|
"""Returns the number of matching docstring sections."""
|
|
return sum(
|
|
bool(i)
|
|
for i in (
|
|
self.re_param_in_docstring.search(self.doc),
|
|
self.re_raise_in_docstring.search(self.doc),
|
|
self.re_rtype_in_docstring.search(self.doc),
|
|
self.re_returns_in_docstring.search(self.doc),
|
|
self.re_property_type_in_docstring.search(self.doc),
|
|
)
|
|
)
|
|
|
|
def exceptions(self) -> set[str]:
|
|
types: set[str] = set()
|
|
|
|
for match in re.finditer(self.re_raise_in_docstring, self.doc):
|
|
raise_type = match.group(1)
|
|
types.update(_split_multiple_exc_types(raise_type))
|
|
|
|
return types
|
|
|
|
def has_params(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
return self.re_param_in_docstring.search(self.doc) is not None
|
|
|
|
def has_returns(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
return bool(self.re_returns_in_docstring.search(self.doc))
|
|
|
|
def has_rtype(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
return bool(self.re_rtype_in_docstring.search(self.doc))
|
|
|
|
def has_property_returns(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
# The summary line is the return doc,
|
|
# so the first line must not be a known directive.
|
|
return not self.doc.lstrip().startswith(":")
|
|
|
|
def has_property_type(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
return bool(self.re_property_type_in_docstring.search(self.doc))
|
|
|
|
def match_param_docs(self) -> tuple[set[str], set[str]]:
|
|
params_with_doc = set()
|
|
params_with_type = set()
|
|
|
|
for match in re.finditer(self.re_param_in_docstring, self.doc):
|
|
name = match.group(2)
|
|
# Remove escape characters necessary for asterisks
|
|
name = name.replace("\\", "")
|
|
params_with_doc.add(name)
|
|
param_type = match.group(1)
|
|
if param_type is not None:
|
|
params_with_type.add(name)
|
|
|
|
params_with_type.update(re.findall(self.re_type_in_docstring, self.doc))
|
|
return params_with_doc, params_with_type
|
|
|
|
|
|
class EpytextDocstring(SphinxDocstring):
|
|
"""Epytext is similar to Sphinx.
|
|
|
|
See the docs:
|
|
http://epydoc.sourceforge.net/epytext.html
|
|
http://epydoc.sourceforge.net/fields.html#fields
|
|
|
|
It's used in PyCharm:
|
|
https://www.jetbrains.com/help/pycharm/2016.1/creating-documentation-comments.html#d848203e314
|
|
https://www.jetbrains.com/help/pycharm/2016.1/using-docstrings-to-specify-types.html
|
|
"""
|
|
|
|
re_param_in_docstring = re.compile(
|
|
SphinxDocstring.re_param_raw.replace(":", "@", 1), re.X | re.S
|
|
)
|
|
|
|
re_type_in_docstring = re.compile(
|
|
SphinxDocstring.re_type_raw.replace(":", "@", 1), re.X | re.S
|
|
)
|
|
|
|
re_property_type_in_docstring = re.compile(
|
|
SphinxDocstring.re_property_type_raw.replace(":", "@", 1), re.X | re.S
|
|
)
|
|
|
|
re_raise_in_docstring = re.compile(
|
|
SphinxDocstring.re_raise_raw.replace(":", "@", 1), re.X | re.S
|
|
)
|
|
|
|
re_rtype_in_docstring = re.compile(
|
|
r"""
|
|
@ # initial "at" symbol
|
|
(?: # Epytext keyword
|
|
rtype|returntype
|
|
)
|
|
: # final colon
|
|
""",
|
|
re.X | re.S,
|
|
)
|
|
|
|
re_returns_in_docstring = re.compile(r"@returns?:")
|
|
|
|
def has_property_returns(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
# If this is a property docstring, the summary is the return doc.
|
|
if self.has_property_type():
|
|
# The summary line is the return doc,
|
|
# so the first line must not be a known directive.
|
|
return not self.doc.lstrip().startswith("@")
|
|
|
|
return False
|
|
|
|
|
|
class GoogleDocstring(Docstring):
|
|
re_type = SphinxDocstring.re_type
|
|
|
|
re_xref = SphinxDocstring.re_xref
|
|
|
|
re_container_type = rf"""
|
|
(?:{re_type}|{re_xref}) # a container type
|
|
[\(\[] [^\n]+ [\)\]] # with the contents of the container
|
|
"""
|
|
|
|
re_multiple_type = rf"""
|
|
(?:{re_container_type}|{re_type}|{re_xref})
|
|
(?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{re_container_type}|{re_type}|{re_xref}))*
|
|
"""
|
|
|
|
_re_section_template = r"""
|
|
^([ ]*) {0} \s*: \s*$ # Google parameter header
|
|
( .* ) # section
|
|
"""
|
|
|
|
re_param_section = re.compile(
|
|
_re_section_template.format(r"(?:Args|Arguments|Parameters)"),
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_keyword_param_section = re.compile(
|
|
_re_section_template.format(r"Keyword\s(?:Args|Arguments|Parameters)"),
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_param_line = re.compile(
|
|
rf"""
|
|
\s* ((?:\\?\*{{0,2}})?[\w\\]+) # identifier potentially with asterisks or escaped `\`
|
|
\s* ( [(]
|
|
{re_multiple_type}
|
|
(?:,\s+optional)?
|
|
[)] )? \s* : # optional type declaration
|
|
\s* (.*) # beginning of optional description
|
|
""",
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_raise_section = re.compile(
|
|
_re_section_template.format(r"Raises"), re.X | re.S | re.M
|
|
)
|
|
|
|
re_raise_line = re.compile(
|
|
rf"""
|
|
\s* ({re_multiple_type}) \s* : # identifier
|
|
\s* (.*) # beginning of optional description
|
|
""",
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_returns_section = re.compile(
|
|
_re_section_template.format(r"Returns?"), re.X | re.S | re.M
|
|
)
|
|
|
|
re_returns_line = re.compile(
|
|
rf"""
|
|
\s* ({re_multiple_type}:)? # identifier
|
|
\s* (.*) # beginning of description
|
|
""",
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_property_returns_line = re.compile(
|
|
rf"""
|
|
^{re_multiple_type}: # identifier
|
|
\s* (.*) # Summary line / description
|
|
""",
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_yields_section = re.compile(
|
|
_re_section_template.format(r"Yields?"), re.X | re.S | re.M
|
|
)
|
|
|
|
re_yields_line = re_returns_line
|
|
|
|
supports_yields = True
|
|
|
|
def matching_sections(self) -> int:
|
|
"""Returns the number of matching docstring sections."""
|
|
return sum(
|
|
bool(i)
|
|
for i in (
|
|
self.re_param_section.search(self.doc),
|
|
self.re_raise_section.search(self.doc),
|
|
self.re_returns_section.search(self.doc),
|
|
self.re_yields_section.search(self.doc),
|
|
self.re_property_returns_line.search(self._first_line()),
|
|
)
|
|
)
|
|
|
|
def has_params(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
return self.re_param_section.search(self.doc) is not None
|
|
|
|
def has_returns(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
entries = self._parse_section(self.re_returns_section)
|
|
for entry in entries:
|
|
match = self.re_returns_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
return_desc = match.group(2)
|
|
if return_desc:
|
|
return True
|
|
|
|
return False
|
|
|
|
def has_rtype(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
entries = self._parse_section(self.re_returns_section)
|
|
for entry in entries:
|
|
match = self.re_returns_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
return_type = match.group(1)
|
|
if return_type:
|
|
return True
|
|
|
|
return False
|
|
|
|
def has_property_returns(self) -> bool:
|
|
# The summary line is the return doc,
|
|
# so the first line must not be a known directive.
|
|
first_line = self._first_line()
|
|
return not bool(
|
|
self.re_param_section.search(first_line)
|
|
or self.re_raise_section.search(first_line)
|
|
or self.re_returns_section.search(first_line)
|
|
or self.re_yields_section.search(first_line)
|
|
)
|
|
|
|
def has_property_type(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
return bool(self.re_property_returns_line.match(self._first_line()))
|
|
|
|
def has_yields(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
entries = self._parse_section(self.re_yields_section)
|
|
for entry in entries:
|
|
match = self.re_yields_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
yield_desc = match.group(2)
|
|
if yield_desc:
|
|
return True
|
|
|
|
return False
|
|
|
|
def has_yields_type(self) -> bool:
|
|
if not self.doc:
|
|
return False
|
|
|
|
entries = self._parse_section(self.re_yields_section)
|
|
for entry in entries:
|
|
match = self.re_yields_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
yield_type = match.group(1)
|
|
if yield_type:
|
|
return True
|
|
|
|
return False
|
|
|
|
def exceptions(self) -> set[str]:
|
|
types: set[str] = set()
|
|
|
|
entries = self._parse_section(self.re_raise_section)
|
|
for entry in entries:
|
|
match = self.re_raise_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
exc_type = match.group(1)
|
|
exc_desc = match.group(2)
|
|
if exc_desc:
|
|
types.update(_split_multiple_exc_types(exc_type))
|
|
|
|
return types
|
|
|
|
def match_param_docs(self) -> tuple[set[str], set[str]]:
|
|
params_with_doc: set[str] = set()
|
|
params_with_type: set[str] = set()
|
|
|
|
entries = self._parse_section(self.re_param_section)
|
|
entries.extend(self._parse_section(self.re_keyword_param_section))
|
|
for entry in entries:
|
|
match = self.re_param_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
param_name = match.group(1)
|
|
# Remove escape characters necessary for asterisks
|
|
param_name = param_name.replace("\\", "")
|
|
|
|
param_type = match.group(2)
|
|
param_desc = match.group(3)
|
|
|
|
if param_type:
|
|
params_with_type.add(param_name)
|
|
|
|
if param_desc:
|
|
params_with_doc.add(param_name)
|
|
|
|
return params_with_doc, params_with_type
|
|
|
|
def _first_line(self) -> str:
|
|
return self.doc.lstrip().split("\n", 1)[0]
|
|
|
|
@staticmethod
|
|
def min_section_indent(section_match: re.Match[str]) -> int:
|
|
return len(section_match.group(1)) + 1
|
|
|
|
@staticmethod
|
|
def _is_section_header(_: str) -> bool:
|
|
# Google parsing does not need to detect section headers,
|
|
# because it works off of indentation level only
|
|
return False
|
|
|
|
def _parse_section(self, section_re: re.Pattern[str]) -> list[str]:
|
|
section_match = section_re.search(self.doc)
|
|
if section_match is None:
|
|
return []
|
|
|
|
min_indentation = self.min_section_indent(section_match)
|
|
|
|
entries: list[str] = []
|
|
entry: list[str] = []
|
|
is_first = True
|
|
for line in section_match.group(2).splitlines():
|
|
if not line.strip():
|
|
continue
|
|
indentation = space_indentation(line)
|
|
if indentation < min_indentation:
|
|
break
|
|
|
|
# The first line after the header defines the minimum
|
|
# indentation.
|
|
if is_first:
|
|
min_indentation = indentation
|
|
is_first = False
|
|
|
|
if indentation == min_indentation:
|
|
if self._is_section_header(line):
|
|
break
|
|
# Lines with minimum indentation must contain the beginning
|
|
# of a new parameter documentation.
|
|
if entry:
|
|
entries.append("\n".join(entry))
|
|
entry = []
|
|
|
|
entry.append(line)
|
|
|
|
if entry:
|
|
entries.append("\n".join(entry))
|
|
|
|
return entries
|
|
|
|
|
|
class NumpyDocstring(GoogleDocstring):
|
|
_re_section_template = r"""
|
|
^([ ]*) {0} \s*?$ # Numpy parameters header
|
|
\s* [-=]+ \s*?$ # underline
|
|
( .* ) # section
|
|
"""
|
|
|
|
re_param_section = re.compile(
|
|
_re_section_template.format(r"(?:Args|Arguments|Parameters)"),
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_default_value = r"""((['"]\w+\s*['"])|(\d+)|(True)|(False)|(None))"""
|
|
|
|
re_param_line = re.compile(
|
|
rf"""
|
|
\s* (?P<param_name>\*{{0,2}}\w+)(\s?(:|\n)) # identifier with potential asterisks
|
|
\s*
|
|
(?P<param_type>
|
|
(
|
|
({GoogleDocstring.re_multiple_type}) # default type declaration
|
|
(,\s+optional)? # optional 'optional' indication
|
|
)?
|
|
(
|
|
{{({re_default_value},?\s*)+}} # set of default values
|
|
)?
|
|
(?:$|\n)
|
|
)?
|
|
(
|
|
\s* (?P<param_desc>.*) # optional description
|
|
)?
|
|
""",
|
|
re.X | re.S,
|
|
)
|
|
|
|
re_raise_section = re.compile(
|
|
_re_section_template.format(r"Raises"), re.X | re.S | re.M
|
|
)
|
|
|
|
re_raise_line = re.compile(
|
|
rf"""
|
|
\s* ({GoogleDocstring.re_type})$ # type declaration
|
|
\s* (.*) # optional description
|
|
""",
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_returns_section = re.compile(
|
|
_re_section_template.format(r"Returns?"), re.X | re.S | re.M
|
|
)
|
|
|
|
re_returns_line = re.compile(
|
|
rf"""
|
|
\s* (?:\w+\s+:\s+)? # optional name
|
|
({GoogleDocstring.re_multiple_type})$ # type declaration
|
|
\s* (.*) # optional description
|
|
""",
|
|
re.X | re.S | re.M,
|
|
)
|
|
|
|
re_yields_section = re.compile(
|
|
_re_section_template.format(r"Yields?"), re.X | re.S | re.M
|
|
)
|
|
|
|
re_yields_line = re_returns_line
|
|
|
|
supports_yields = True
|
|
|
|
def match_param_docs(self) -> tuple[set[str], set[str]]:
|
|
"""Matches parameter documentation section to parameter documentation rules."""
|
|
params_with_doc = set()
|
|
params_with_type = set()
|
|
|
|
entries = self._parse_section(self.re_param_section)
|
|
entries.extend(self._parse_section(self.re_keyword_param_section))
|
|
for entry in entries:
|
|
match = self.re_param_line.match(entry)
|
|
if not match:
|
|
continue
|
|
|
|
# check if parameter has description only
|
|
re_only_desc = re.match(r"\s*(\*{0,2}\w+)\s*:?\n\s*\w*$", entry)
|
|
if re_only_desc:
|
|
param_name = match.group("param_name")
|
|
param_desc = match.group("param_type")
|
|
param_type = None
|
|
else:
|
|
param_name = match.group("param_name")
|
|
param_type = match.group("param_type")
|
|
param_desc = match.group("param_desc")
|
|
# The re_param_line pattern needs to match multi-line which removes the ability
|
|
# to match a single line description like 'arg : a number type.'
|
|
# We are not trying to determine whether 'a number type' is correct typing
|
|
# but we do accept it as typing as it is in the place where typing
|
|
# should be
|
|
if param_type is None and re.match(r"\s*(\*{0,2}\w+)\s*:.+$", entry):
|
|
param_type = param_desc
|
|
# If the description is "" but we have a type description
|
|
# we consider the description to be the type
|
|
if not param_desc and param_type:
|
|
param_desc = param_type
|
|
|
|
if param_type:
|
|
params_with_type.add(param_name)
|
|
|
|
if param_desc:
|
|
params_with_doc.add(param_name)
|
|
|
|
return params_with_doc, params_with_type
|
|
|
|
@staticmethod
|
|
def min_section_indent(section_match: re.Match[str]) -> int:
|
|
return len(section_match.group(1))
|
|
|
|
@staticmethod
|
|
def _is_section_header(line: str) -> bool:
|
|
return bool(re.match(r"\s*-+$", line))
|
|
|
|
|
|
DOCSTRING_TYPES = {
|
|
"sphinx": SphinxDocstring,
|
|
"epytext": EpytextDocstring,
|
|
"google": GoogleDocstring,
|
|
"numpy": NumpyDocstring,
|
|
"default": Docstring,
|
|
}
|
|
"""A map of the name of the docstring type to its class.
|
|
|
|
:type: dict(str, type)
|
|
"""
|