stubber.codemod.merge_docstub

Merge documentation and type information - from an doctring-rich and typed stub module - infor a less well documented and typed stub module

Attributes

Mod_Class_T

TypeVar for Module or ClassDef that both support overloads

empty_module

_code

Classes

MergeCommand

A libcst transformer that merges the type-rich information from a doc-stub into

Functions

is_decorator(→ bool)

shorthand to determin if something is a specific decorator (simple name only)

is_mp_available_decorator(→ bool)

True if decorator is mp_available in any form: @mp_available, @mp_available(...), @_pkg.mp_available, @_pkg.mp_available(...).

is_empty_mp_available_call(→ bool)

True if decorator is exactly a zero-arg call to mp_available (qualified or not).

Module Contents

stubber.codemod.merge_docstub.Mod_Class_T

TypeVar for Module or ClassDef that both support overloads

stubber.codemod.merge_docstub.empty_module
stubber.codemod.merge_docstub._code
stubber.codemod.merge_docstub.is_decorator(dec: libcst.CSTNode, name: str) → bool

shorthand to determin if something is a specific decorator (simple name only)

Parameters:

  • dec (libcst.CSTNode)

  • name (str)

Return type:

bool

stubber.codemod.merge_docstub.is_mp_available_decorator(dec: libcst.CSTNode) → bool

True if decorator is mp_available in any form: @mp_available, @mp_available(…), @_pkg.mp_available, @_pkg.mp_available(…).

Parameters:

dec (libcst.CSTNode)

Return type:

bool

stubber.codemod.merge_docstub.is_empty_mp_available_call(dec: libcst.CSTNode) → bool

True if decorator is exactly a zero-arg call to mp_available (qualified or not).

Parameters:

dec (libcst.CSTNode)

Return type:

bool

class stubber.codemod.merge_docstub.MergeCommand(context: libcst.codemod.CodemodContext, docstub_file: pathlib.Path | str, copy_params: bool = False, copy_docstr: bool = True, copy_returns: bool = False)

Bases: libcst.codemod.VisitorBasedCodemodCommand

A libcst transformer that merges the type-rich information from a doc-stub into a firmware stub. The resulting file will contain information from both sources.

  • module docstring - from source

  • function parameters and types - from docstubs

  • function return types - from docstubs

  • function docstrings - from source

Parameters:

  • context (libcst.codemod.CodemodContext)

  • docstub_file (Union[pathlib.Path, str])

  • copy_params (bool)

  • copy_docstr (bool)

  • copy_returns (bool)

DESCRIPTION: str = 'Merge the type-rich information from a doc-stub into a firmware stub'
copy_params: bool = True
copy_docstr: bool = True
copy_returns: bool = False
static add_args(arg_parser: argparse.ArgumentParser) → None

Add command-line args that a user can specify for running this codemod.

Parameters:

arg_parser (argparse.ArgumentParser)

Return type:

None

replace_functiondef_with_classdef = True
stack: List[str] = []
docstub_path
docstub_source
annotations: Dict[Tuple[str, Ellipsis], stubber.typing_collector.AnnoValue]
comments: List[str] = []
stub_imports: Dict[str, libcst.codemod.visitors.ImportItem]
all_imports: List[libcst.Import | libcst.ImportFrom] = []
type_helpers
leave_Module(original_node: libcst.Module, updated_node: libcst.Module) → libcst.Module

This method is responsible for updating the module node after processing it in the codemod. It performs the following tasks: 1. Adds any needed imports from the doc-stub. 2. Adds from module import * from the doc-stub. 3. Updates the module docstring. 4. Updates the comments in the module.

Parameters:

  • original_node (libcst.Module) – The original module node.

  • updated_node (libcst.Module) – The updated module node after processing.

Returns:

The updated module node.

Return type:

libcst.Module

add_missed_overloads(updated_node: Mod_Class_T, stack_id: tuple) → Mod_Class_T

Add any missing overloads to the updated_node

Parameters:

  • updated_node (Mod_Class_T)

  • stack_id (tuple)

Return type:

Mod_Class_T

add_missed_mp_available(updated_node: Mod_Class_T, stack_id: tuple) → Mod_Class_T

Add any missing @mp_available to the updated_node

Parameters:

  • updated_node (Mod_Class_T)

  • stack_id (tuple)

Return type:

Mod_Class_T

add_missed_literal_docstrings(updated_node: Mod_Class_T, stack_id: tuple) → Mod_Class_T

Add any missing literal docstrings to the updated_node

Parameters:

  • updated_node (Mod_Class_T)

  • stack_id (tuple)

Return type:

Mod_Class_T

locate_function_by_name(overload, updated_body)

locate the (last) function or class by name

visit_ClassDef(node: libcst.ClassDef) → bool | None

keep track of the the (class, method) names to the stack

Parameters:

node (libcst.ClassDef)

Return type:

Optional[bool]

leave_ClassDef(original_node: libcst.ClassDef, updated_node: libcst.ClassDef) → libcst.ClassDef
Parameters:

  • original_node (libcst.ClassDef)

  • updated_node (libcst.ClassDef)

Return type:

libcst.ClassDef

visit_FunctionDef(node: libcst.FunctionDef) → bool | None
Parameters:

node (libcst.FunctionDef)

Return type:

Optional[bool]

leave_FunctionDef(original_node: libcst.FunctionDef, updated_node: libcst.FunctionDef) → libcst.FunctionDef | libcst.ClassDef

Update the function Parameters and return type, decorators and docstring

Parameters:

  • original_node (libcst.FunctionDef)

  • updated_node (libcst.FunctionDef)

Return type:

Union[libcst.FunctionDef, libcst.ClassDef]

merge_decorator(original_node: libcst.FunctionDef, updated_node: libcst.FunctionDef, stack_id, doc_stub)
Parameters:

  • original_node (libcst.FunctionDef)

  • updated_node (libcst.FunctionDef)