Docstring Parser Fork

Warnings

• gotcha This library is a fork of `docstring_parser` and shares the same import path (`from docstring_parser import ...`). If both the original `docstring_parser` and `docstring-parser-fork` are installed, unexpected behavior or conflicts may occur due to Python's import resolution order.
  Fix: Ensure only one of the two libraries (`docstring_parser` or `docstring-parser-fork`) is installed in your environment to avoid import collisions.
• breaking The fork explicitly fixes bugs and offers additional functionalities compared to the upstream `docstring_parser`. While intended as improvements, users migrating from the original library should review the `CHANGELOG.md` file for entries marked '(Fork)' to understand specific behavioral changes that might affect existing code relying on previous `docstring_parser` quirks or omissions.
  Fix: Consult the `CHANGELOG.md` in the project repository for detailed differences and adjust code as necessary, especially for edge cases in docstring parsing that the fork may now handle differently or correctly.
• gotcha When parsing attribute docstrings, the `parse_from_object` function currently only supports attributes defined at class and module levels. Attribute docstrings defined within `__init__` methods are not supported. Additionally, when given a class, only attribute docstrings of that specific class are parsed, not inherited ones.
  Fix: For attribute docstrings in `__init__`, consider moving them to class or module level, or using direct `__doc__` attributes where possible. For inherited attributes, separate calls to `parse_from_object` for parent classes are required if their attribute docstrings are needed.

Install

• pip install docstring-parser-fork PyPI
• conda install -c conda-forge docstring_parser Conda (note: package name is 'docstring_parser')

Imports

• parse

  from docstring_parser import parse

  Despite the package name 'docstring-parser-fork', the import path remains 'docstring_parser' for compatibility with the upstream library.
• DocstringStyle

  from docstring_parser import DocstringStyle

  Used to specify or infer docstring styles during parsing.

Quickstart

This example demonstrates how to parse a function's docstring using the `parse` function and access its components like short description, long description, parameters, and raised exceptions. The `DocstringStyle.AUTO` option attempts to automatically detect the docstring format.

from docstring_parser import parse, DocstringStyle

def example_function(name: str, priority: int = 1) -> None:
    """
    Short description.

    Long description spanning multiple lines
    - First line
    - Second line
    - Third line

    :param name: description 1
    :param int priority: description 2
    :raises ValueError: if name is invalid
    """
    pass

docstring = parse(example_function.__doc__, style=DocstringStyle.AUTO)

print(f"Short description: {docstring.short_description}")
print(f"Long description: {docstring.long_description}")
for param in docstring.params:
    print(f"Param: {param.arg_name}, Type: {param.type_name}, Description: {param.description}")
for rais in docstring.raises:
    print(f"Raises: {rais.type_name}, Description: {rais.description}")