Skip to main content

Google Docstring Parser

Project description

gdparser

google docstring parser

No dependencies required.

def test_func(text, k=3, e='base'):
    """This is a test function

    Args:
        text (str): this is text given by user

    Keyword Arguments:
        k (int): this is integer
        e (str): values should be in {'aa', 'bb'}

    Returns:
        None

    Examples:

        >>> text("dddd")
        # None
    """
    return None



from gdparser import parse

parse(test_func.__doc__)

{'description': 'This is a test function\n    \n    ',
 'parameters': [{'description': 'this is text given by user',
                 'enum': None,
                 'name': 'text',
                 'required': True,
                 'type': 'string'},
                {'description': 'this is integer',
                 'enum': None,
                 'name': 'k',
                 'required': False,
                 'type': 'integer'},
                {'description': "values should be in {'aa', 'bb'}",
                 'enum': ['aa', 'bb'],
                 'name': 'e',
                 'required': False,
                 'type': 'string'}],
 'sections': [{'section_body': 'None\n        \n    ',
               'section_header': 'Returns'},
              {'section_body': '        \n>>> text("dddd")\n# None\n    ',
               'section_header': 'Examples'}]}

Install

pip install gdparser

Usage

see the docstring of parse method

Parses Google-style Docstring.

    Args:
        text (str): docstring to parse written in Google-docstring format.

    Keyword Arguments:
        supported_headers (List[str] or None): list of text which can be recognized as the section headers, 
            if None, the values are
            ['Args', 'Arguments', 'Attention', 'Attributes', 'Caution', 'Danger',
             'Error', 'Example', 'Examples', 'Example Request', 'Hint', 'Important', 'Keyword Args',
             'Keyword Arguments', 'Kwargs', 'Methods', 'Note', 'Notes', 'Other Parameters',
             'Parameters', 'Return', 'Returns', 'Raises', 'References', 'See Also',
             'Tip', 'Todo', 'Warning', 'Warnings', 'Warns', 'Yield', 'Yields']

        args_headers (List[str] or None): list of text which can be recognized as the argument section headers. 
            Argument section headers is special which is parsed and fill the parameters of the final output.
            if None, the values are
            ['Args', 'Arguments', 'Parameters']

        kwargs_headers (List[str] or None): same as the args headers, except that the 'required' key of each parameter will become False.
            if None, the values are
            ['Kwargs', 'Keyword Args', 'Keyword Arguments']

        remove_indent (bool): whether indent is deleted or not. indent is defined as the 
            common whitespace length across the lines within same section.

        javascript_type (bool): whether the python type notation should be converted into javascript type.
            currently following four types are converted.
            'str'- 'string', 'int'- 'integer', 'bool'- 'boolean', 'float'- 'number'
            if the type is not in the among the supported types, returned as it is without conversion.

    Returns:
        dict: 
            - description (str) : function description
            - sections (List[Dict]) : the list of each section, each section is composed of two keys,
                 - section_header (str) 
                 - section_body (str)
            - parameters (List[Dict]) : the list of each parameter, each parameter is composed of five keys,
                 - name (str): parameter name
                 - type (str): parameter type
                 - description (str): parameter description
                 - required (bool) : when the parameter is found in the Args section, it becomes True. 
                      if found in Kwargs section, it become False
                 - enum (List or None) : You can make enum notation by using curly braces in the parameter description. 
                      if the curly brace notation can be evaluated as set, the set value is used.
                      e.g. {'ab', 'cd'} - ['ab', 'cd']
                           {10, 20, 30} - [10, 20, 30]

Changelog

  • 0.0.1 : Initial commit
  • 0.0.2 : Add docstrings, test cases, and fix minor bug (section header startswith non-blank character is recognized as valid section header)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

gdparser-0.0.2-py3-none-any.whl (16.1 kB view details)

Uploaded Python 3

File details

Details for the file gdparser-0.0.2-py3-none-any.whl.

File metadata

  • Download URL: gdparser-0.0.2-py3-none-any.whl
  • Upload date:
  • Size: 16.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.4

File hashes

Hashes for gdparser-0.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 af4f869f0b398055eb7c7cce22af0771d7b9a3bce32907997e12a062001002fb
MD5 f40c626926b4d91965e83bd31089126a
BLAKE2b-256 163a0db3869a5b38fb720f54a7f25a610d79f12a59050948594ee319fd997775

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page