xdev.cli.docstr_stubgen module

Script for auto-generating pyi type extension files from google-style docstrings.

This is a work in progress, but ultimately the goal is to be able to express concise typing information in docstrings and then explicitly expose that to Python.

Requirements:

pip install mypy autoflake yapf

CommandLine

# Run script to parse google-style docstrings and write pyi files

xdev doctypes --module=xdev
python ~/code/xdev/xdev/cli/docstr_stubgen.py

See:
~/code/mypy/mypy/stubgen.py

# Run mypy to check that type annotations are correct
mypy ubelt

xdev.cli.docstr_stubgen._hack_away_compiled_mypy()

Worked with: mypy-0.970+dev.ddbea6988c0913c70ed16cd2fda6064e301b4b63

Note

# Can also do pip uninstall mypy pip install -U mypy –no-binary :all:

xdev.cli.docstr_stubgen.generate_typed_stubs(modpath)

Attempt to use google-style docstrings, xdoctest, and mypy to generate typed stub files.

Does not overwrite anything by itself.

Parameters:

modpath (PathLike) – path to the module to generate types for

Returns:

A dictionary mapping the path of each file to write to the text to be written.

Return type:

Dict[PathLike, str]

Notes

FIXME: This currently requires my hacked version of mypy

CommandLine

xdoctest -m /home/joncrall/code/xdev/xdev/cli/docstr_stubgen.py generate_typed_stubs --hacked

Example

>>> # xdoctest: +REQUIRES(module:mypy)
>>> # xdoctest: +REQUIRES(--hacked)
>>> from xdev.cli.docstr_stubgen import *  # NOQA
>>> import xdev
>>> import ubelt as ub
>>> from xdev.cli import docstr_stubgen
>>> modpath = ub.Path(docstr_stubgen.__file__)
>>> generated = generate_typed_stubs(modpath)
>>> text = generated[ub.peek(generated.keys())]
>>> assert 'PathLike' in text
>>> assert 'Dict' in text
>>> print(text)

xdev.cli.docstr_stubgen.delete_unpaired_pyi_files(modpath)

Cleanup pyi files corresponding to renamed or removed py files.

xdev.cli.docstr_stubgen.remove_duplicate_imports(text)

xdev.cli.docstr_stubgen.postprocess_hacks(text, mod)

xdev.cli.docstr_stubgen.stdlib_names()

xdev.cli.docstr_stubgen.common_module_names()

fpath = ub.grabdata(’https://raw.githubusercontent.com/hugovk/top-pypi-packages/main/top-pypi-packages-30-days.json’, expires=86400) fpath = ub.Path(fpath) import json data = json.loads(fpath.read_text()) for item in data[‘rows’][0:300]:

pkg_name = item[‘project’] if ‘-’ not in pkg_name:

print(f’{pkg_name!r},’)

xdev.cli.docstr_stubgen.common_module_aliases()

xdev.cli.docstr_stubgen.common_unreferenced()

xdev.cli.docstr_stubgen.hacked_typing_info(type_name)

class xdev.cli.docstr_stubgen.ExtendedStubGenerator

Bases: object

_hack_for_info(info)

visit_func_def(o: None, is_abstract: bool = False, is_overload: bool = False) → None

process_decorator(o) → None

visit_class_def(o) → None

xdev.cli.docstr_stubgen.modpath_coerce(modpath_coercable)

if modpath_coercable is a name, statically converts it to a path

Parameters:

modpath_coercable (str | PathLike | ModuleType) – something we can extract a path to a module from.

Returns:

the coerced modpath

Return type:

str

Example

>>> # xdoctest: +SKIP
>>> from xdev.cli.docstr_stubgen import *  # NOQA
>>> import xdev
>>> modpath_coercable = xdev
>>> modpath = modpath_coerce(modpath_coercable)
>>> print(f'modpath={modpath}')
>>> assert modpath_coerce(modpath) == modpath
>>> assert modpath_coerce(xdev.__name__) == modpath