Awesome
docify
A script to add docstrings to Python type stubs using reflection
Features
- Uses LibCST to parse and modify the stub file
- Dynamically imports the actual module to get the runtime docstring
- Handles most
sys.version
andsys.platform
conditional blocks, will only add docstrings to the correct branch - Able to modify files in-place with
-i
or--in-place
- Won't overwrite existing docstrings
- With
-b
or--builtins-only
, will only add docstrings for modules found insys.builtin_module_names
(stdlib modules written in C). - With
--if-needed
, will only add docstrings if the object's (Python) source code is unavailable. Useful for language servers like basedpyright that are able to extract docstrings from source code.
Installation
Install from PyPI:
pip install docify
docify
# or
python -m docify
Or just download and run the script directly:
# Install dependencies
pip install libcst tqdm # tqdm is not needed if running with -q
python docify.py
# or
python -m docify
# or
chmod +x docify.py
./docify.py
Usage
docify [-h] [-V] [-v] [-q] [-b] [--if-needed] (-i | -o OUTPUT_DIR) INPUT_DIR [INPUT_DIR ...]
A script to add docstrings to Python type stubs using reflection
positional arguments:
INPUT_DIR directory to read stubs from
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-b, --builtins-only only add docstrings to modules found in `sys.builtin_module_names`
--if-needed only add a docstring if the object's source code cannot be found
-i, --in-place modify stubs in-place
-o OUTPUT_DIR, --output OUTPUT_DIR
directory to write modified stubs to