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_inspect_placeholder_params`(→ bool)	Return whether params contains only MicroPython inspect dummy names.
`_is_unknown_params`(→ bool)	Return whether params lacks meaningful parameter information.
`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).
`_typehelper_name`(→ Optional[str])	Return the simple target name of a type-helper assignment, or None.
`_assign_target_name`(→ Optional[str])	Return the target name of a simple assignment statement, or None.
`_is_docstring_stmt`(→ bool)	Return whether the statement is a bare string expression (docstring).

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_inspect_placeholder_params(params: str) → bool¶

Return whether params contains only MicroPython inspect dummy names.

Parameters:: params (str)
Return type:: bool

stubber.codemod.merge_docstub._is_unknown_params(params: str) → bool¶

Return whether params lacks meaningful parameter information.

Parameters:: params (str)
Return type:: bool

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

stubber.codemod.merge_docstub._typehelper_name(node: libcst.CSTNode) → str | None¶

Return the simple target name of a type-helper assignment, or None.

Used to de-duplicate type-helpers (TypeVars, TypeAliases, constants) when merging several doc-stubs into a single transform pass.

Parameters:: node (libcst.CSTNode)
Return type:: Optional[str]

stubber.codemod.merge_docstub._assign_target_name(stmt: libcst.CSTNode) → str | None¶

Return the target name of a simple assignment statement, or None.

Parameters:: stmt (libcst.CSTNode)
Return type:: Optional[str]

stubber.codemod.merge_docstub._is_docstring_stmt(stmt: libcst.CSTNode) → bool¶

Return whether the statement is a bare string expression (docstring).

Parameters:: stmt (libcst.CSTNode)
Return type:: bool

class stubber.codemod.merge_docstub.MergeCommand(context: libcst.codemod.CodemodContext, docstub_file: pathlib.Path | str | Sequence[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, Sequence[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¶

annotations: Dict[Tuple[str, ...], 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_mp_available_attributes(updated_node: Mod_Class_T, stack_id: tuple) → Mod_Class_T¶

Add attribute assignments marked with a # mp_available comment that are missing from the target. This is the attribute equivalent of the @mp_available decorator: it force-merges documented module- or class-level attributes that createstubs cannot detect on-device.

When the attribute already exists in the target, the # mp_available marker is propagated onto it so it survives further source>dest>final merge steps.

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)