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.

It seems that mypy updates break this code extremely frequently. It is hard to keep this maintained.

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.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