Skip to content

GoogleDocParser

Bases: AbstractDocstringParser

Parses documentation in the Googledoc format. See https://google.github.io/styleguide/pyguide.html#381-docstrings for more information.

This class is not thread-safe. Each thread should create its own instance.

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
class GoogleDocParser(AbstractDocstringParser):
    """
    Parses documentation in the Googledoc format. See https://google.github.io/styleguide/pyguide.html#381-docstrings for more information.

    This class is not thread-safe. Each thread should create its own instance.
    """

    def __init__(self) -> None:
        self.__cached_function_node: astroid.FunctionDef | None = None
        self.__cached_docstring: DocstringParam | None = None

    def get_class_documentation(self, class_node: astroid.ClassDef) -> ClassDocstring:
        docstring = get_full_docstring(class_node)
        docstring_obj = parse_docstring(docstring, style=DocstringStyle.GOOGLE)

        return ClassDocstring(
            description=get_description(docstring_obj),
            full_docstring=docstring,
        )

    def get_function_documentation(self, function_node: astroid.FunctionDef) -> FunctionDocstring:
        docstring = get_full_docstring(function_node)
        docstring_obj = self.__get_cached_function_googledoc_string(function_node, docstring)

        return FunctionDocstring(
            description=get_description(docstring_obj),
            full_docstring=docstring,
        )

    def get_parameter_documentation(
        self,
        function_node: astroid.FunctionDef,
        parameter_name: str,
        parameter_assigned_by: ParameterAssignment,  # noqa: ARG002
    ) -> ParameterDocstring:
        # For constructors (__init__ functions) the parameters are described on the class
        if function_node.name == "__init__" and isinstance(function_node.parent, astroid.ClassDef):
            docstring = get_full_docstring(function_node.parent)
        else:
            docstring = get_full_docstring(function_node)

        # Find matching parameter docstrings
        function_googledoc = self.__get_cached_function_googledoc_string(function_node, docstring)
        all_parameters_googledoc: list[DocstringParam] = function_googledoc.params
        matching_parameters_googledoc = [
            it for it in all_parameters_googledoc if it.arg_name == parameter_name and it.args[0] == "param"
        ]

        if len(matching_parameters_googledoc) == 0:
            return ParameterDocstring(type="", default_value="", description="")

        last_parameter_docstring_obj = matching_parameters_googledoc[-1]
        return ParameterDocstring(
            type=last_parameter_docstring_obj.type_name or "",
            default_value=last_parameter_docstring_obj.default or "",
            description=last_parameter_docstring_obj.description or "",
        )

    def get_attribute_documentation(
        self,
        function_node: astroid.FunctionDef,
        attribute_name: str,
        attribute_assigned_by: AttributeAssignment,  # noqa: ARG002
    ) -> AttributeDocstring:
        # For constructors (__init__ functions) the attributes are described on the class
        if function_node.name == "__init__" and isinstance(function_node.parent, astroid.ClassDef):
            docstring = get_full_docstring(function_node.parent)
        else:
            docstring = get_full_docstring(function_node)

        # Find matching attribute docstrings
        function_googledoc = self.__get_cached_function_googledoc_string(function_node, docstring)
        all_attributes_googledoc: list[DocstringParam] = function_googledoc.params
        matching_attributes_googledoc = [
            it for it in all_attributes_googledoc if it.arg_name == attribute_name and it.args[0] == "attribute"
        ]

        if len(matching_attributes_googledoc) == 0:
            return AttributeDocstring(type="", default_value="", description="")

        last_attribute_docstring_obj = matching_attributes_googledoc[-1]
        return AttributeDocstring(
            type=last_attribute_docstring_obj.type_name or "",
            default_value=last_attribute_docstring_obj.default or "",
            description=last_attribute_docstring_obj.description,
        )

    def get_result_documentation(self, function_node: astroid.FunctionDef) -> ResultDocstring:
        if function_node.name == "__init__" and isinstance(function_node.parent, astroid.ClassDef):
            docstring = get_full_docstring(function_node.parent)
        else:
            docstring = get_full_docstring(function_node)

        # Find matching parameter docstrings
        function_googledoc = self.__get_cached_function_googledoc_string(function_node, docstring)
        function_returns = function_googledoc.returns

        if function_returns is None:
            return ResultDocstring(type="", description="")

        return ResultDocstring(type=function_returns.type_name or "", description=function_returns.description or "")

    def __get_cached_function_googledoc_string(self, function_node: astroid.FunctionDef, docstring: str) -> Docstring:
        """
        Return the GoogleDocString for the given function node.

        It is only recomputed when the function node differs from the previous one that was passed to this function.
        This avoids reparsing the docstring for the function itself and all of its parameters.

        On Lars's system this caused a significant performance improvement: Previously, 8.382s were spent inside the
        function get_parameter_documentation when parsing sklearn. Afterward, it was only 2.113s.
        """
        if self.__cached_function_node is not function_node:
            self.__cached_function_node = function_node
            self.__cached_docstring = parse_docstring(docstring, style=DocstringStyle.GOOGLE)

        return self.__cached_docstring

__cached_docstring: DocstringParam | None = None instance-attribute

__cached_function_node: astroid.FunctionDef | None = None instance-attribute

__get_cached_function_googledoc_string(function_node, docstring)

Return the GoogleDocString for the given function node.

It is only recomputed when the function node differs from the previous one that was passed to this function. This avoids reparsing the docstring for the function itself and all of its parameters.

On Lars's system this caused a significant performance improvement: Previously, 8.382s were spent inside the function get_parameter_documentation when parsing sklearn. Afterward, it was only 2.113s.

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def __get_cached_function_googledoc_string(self, function_node: astroid.FunctionDef, docstring: str) -> Docstring:
    """
    Return the GoogleDocString for the given function node.

    It is only recomputed when the function node differs from the previous one that was passed to this function.
    This avoids reparsing the docstring for the function itself and all of its parameters.

    On Lars's system this caused a significant performance improvement: Previously, 8.382s were spent inside the
    function get_parameter_documentation when parsing sklearn. Afterward, it was only 2.113s.
    """
    if self.__cached_function_node is not function_node:
        self.__cached_function_node = function_node
        self.__cached_docstring = parse_docstring(docstring, style=DocstringStyle.GOOGLE)

    return self.__cached_docstring

__init__()

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
26
27
28
def __init__(self) -> None:
    self.__cached_function_node: astroid.FunctionDef | None = None
    self.__cached_docstring: DocstringParam | None = None

get_attribute_documentation(function_node, attribute_name, attribute_assigned_by)

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def get_attribute_documentation(
    self,
    function_node: astroid.FunctionDef,
    attribute_name: str,
    attribute_assigned_by: AttributeAssignment,  # noqa: ARG002
) -> AttributeDocstring:
    # For constructors (__init__ functions) the attributes are described on the class
    if function_node.name == "__init__" and isinstance(function_node.parent, astroid.ClassDef):
        docstring = get_full_docstring(function_node.parent)
    else:
        docstring = get_full_docstring(function_node)

    # Find matching attribute docstrings
    function_googledoc = self.__get_cached_function_googledoc_string(function_node, docstring)
    all_attributes_googledoc: list[DocstringParam] = function_googledoc.params
    matching_attributes_googledoc = [
        it for it in all_attributes_googledoc if it.arg_name == attribute_name and it.args[0] == "attribute"
    ]

    if len(matching_attributes_googledoc) == 0:
        return AttributeDocstring(type="", default_value="", description="")

    last_attribute_docstring_obj = matching_attributes_googledoc[-1]
    return AttributeDocstring(
        type=last_attribute_docstring_obj.type_name or "",
        default_value=last_attribute_docstring_obj.default or "",
        description=last_attribute_docstring_obj.description,
    )

get_class_documentation(class_node)

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
30
31
32
33
34
35
36
37
def get_class_documentation(self, class_node: astroid.ClassDef) -> ClassDocstring:
    docstring = get_full_docstring(class_node)
    docstring_obj = parse_docstring(docstring, style=DocstringStyle.GOOGLE)

    return ClassDocstring(
        description=get_description(docstring_obj),
        full_docstring=docstring,
    )

get_function_documentation(function_node)

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
39
40
41
42
43
44
45
46
def get_function_documentation(self, function_node: astroid.FunctionDef) -> FunctionDocstring:
    docstring = get_full_docstring(function_node)
    docstring_obj = self.__get_cached_function_googledoc_string(function_node, docstring)

    return FunctionDocstring(
        description=get_description(docstring_obj),
        full_docstring=docstring,
    )

get_parameter_documentation(function_node, parameter_name, parameter_assigned_by)

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def get_parameter_documentation(
    self,
    function_node: astroid.FunctionDef,
    parameter_name: str,
    parameter_assigned_by: ParameterAssignment,  # noqa: ARG002
) -> ParameterDocstring:
    # For constructors (__init__ functions) the parameters are described on the class
    if function_node.name == "__init__" and isinstance(function_node.parent, astroid.ClassDef):
        docstring = get_full_docstring(function_node.parent)
    else:
        docstring = get_full_docstring(function_node)

    # Find matching parameter docstrings
    function_googledoc = self.__get_cached_function_googledoc_string(function_node, docstring)
    all_parameters_googledoc: list[DocstringParam] = function_googledoc.params
    matching_parameters_googledoc = [
        it for it in all_parameters_googledoc if it.arg_name == parameter_name and it.args[0] == "param"
    ]

    if len(matching_parameters_googledoc) == 0:
        return ParameterDocstring(type="", default_value="", description="")

    last_parameter_docstring_obj = matching_parameters_googledoc[-1]
    return ParameterDocstring(
        type=last_parameter_docstring_obj.type_name or "",
        default_value=last_parameter_docstring_obj.default or "",
        description=last_parameter_docstring_obj.description or "",
    )

get_result_documentation(function_node)

Source code in src/library_analyzer/processing/api/docstring_parsing/_googledoc_parser.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def get_result_documentation(self, function_node: astroid.FunctionDef) -> ResultDocstring:
    if function_node.name == "__init__" and isinstance(function_node.parent, astroid.ClassDef):
        docstring = get_full_docstring(function_node.parent)
    else:
        docstring = get_full_docstring(function_node)

    # Find matching parameter docstrings
    function_googledoc = self.__get_cached_function_googledoc_string(function_node, docstring)
    function_returns = function_googledoc.returns

    if function_returns is None:
        return ResultDocstring(type="", description="")

    return ResultDocstring(type=function_returns.type_name or "", description=function_returns.description or "")