stubdoc is a Python library that append docstring to stub files.
mypy's stubgen command that create stub files does not append docstring. So if stub file exists and IDE prioritize stub's completion then docstring will not appear on IDE.
So that this library add docstring to stub files to display that.
For more mypy's stubgen command details, please see mypy documentation, Automatic stub generation (stubgen).
For example, suppose that the following code's module exists (sample/sample.py):
from random import randint sample_int: int = 100 def sample_func(a: int, b: str) -> bool: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit, ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Parameters ---------- a : int Lorem ipsum dolor sit amet, consectetur adipiscing elit. b : str ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Returns ------- c : bool Ut enim ad minim veniam, quis nostrud exercitation. """ return True class SampleClass: def __init__(self) -> None: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. """ @property def sample_property(self) -> int: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Returns ------- d : int ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. """ return randint(0, 100)mypy's stubgen command will generate stub files as follows (stubgen command will not add docstring):
sample_int: int def sample_func(a: int, b: str) -> bool: ... class SampleClass: def __init__(self) -> None: ... @property def sample_property(self) -> int: ...And then, this library's command will add the docstring to stub doc as follows, so IDE's code completion will show docstring:
sample_int: int def sample_func(a: int, b: str) -> bool: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit, ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Parameters ---------- a : int Lorem ipsum dolor sit amet, consectetur adipiscing elit. b : str ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Returns ------- c : bool Ut enim ad minim veniam, quis nostrud exercitation. """ class SampleClass: def __init__(self) -> None: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. """ @property def sample_property(self) -> int: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Returns ------- d : int ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. """Installation via pip command is provided:
$ pip install stubdoc - Supported Python 3.8 or later (tested on 3.8.5). Probably works on Python 3.6.x or later (but not tested).
Notes: specified module need to be able to import. Stubdoc will replace paths to package path (e.g., 'sample/path.py' to 'sample.path'), so that paths argument can not be specified upper level directory or root directory (e.g., '/sample/path.py' or '../sample/path').
This command will add docstring to stub file. Currently supported one-line stub implementation, like mypy's stubgen command, something as follows: def any_func(a: int, b: str) -> None: ... If line break exists after colon, this command will not work correctly. Also not supported nested function, etc. optional arguments: -h, --help show this help message and exit -m MODULE_PATH, --module_path MODULE_PATH Stub file's original module path. e.g., sample/path.py -s STUB_PATH, --stub_path STUB_PATH Target stub file path. e.g., sample/path.pyi Command example:
$ stubdoc -m samples/sample.py -s out/samples/sample.pyi or
$ stubdoc --module_path samples/sample.py --stub_path out/samples/sample.pyi Or maybe Python interface is useful, like Django environment:
from stubdoc import add_docstring_to_stubfile add_docstring_to_stubfile( original_module_path='sample/path.py', stub_file_path='sample/path.pyi')This library supported only one-line stub implementation, like this:
def sample_func(a: int, b: str) -> bool: ... class SampleClass: def __init__(self) -> None: ... @property def sample_property(self) -> int: ...Not supported line breaks after function's colon:
def sample_func(a: int, b: str) -> bool: ... class SampleClass: def __init__(self) -> None: ... @property def sample_property(self) -> int: passAlso not supported nested functions, like this (docstring will add to only top-level function):
def sample_func_1(a: int, b: str) -> bool: def sample_func_2(c: list) -> None: ...