stubber.codemod.merge_docstub
=============================

.. py:module:: stubber.codemod.merge_docstub

.. autoapi-nested-parse::

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



Attributes
----------

.. autoapisummary::

   stubber.codemod.merge_docstub.Mod_Class_T
   stubber.codemod.merge_docstub.empty_module
   stubber.codemod.merge_docstub._code


Classes
-------

.. autoapisummary::

   stubber.codemod.merge_docstub.MergeCommand


Functions
---------

.. autoapisummary::

   stubber.codemod.merge_docstub.is_decorator
   stubber.codemod.merge_docstub.is_mp_available_decorator
   stubber.codemod.merge_docstub.is_empty_mp_available_call


Module Contents
---------------

.. py:data:: Mod_Class_T

   TypeVar for Module or ClassDef that both support overloads

.. py:data:: empty_module

.. py:data:: _code

.. py:function:: is_decorator(dec: libcst.CSTNode, name: str) -> bool

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


.. py:function:: 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(...).


.. py:function:: is_empty_mp_available_call(dec: libcst.CSTNode) -> bool

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


.. py:class:: MergeCommand(context: libcst.codemod.CodemodContext, docstub_file: Union[pathlib.Path, str], copy_params: bool = False, copy_docstr: bool = True, copy_returns: bool = False)

   Bases: :py:obj:`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



   .. py:attribute:: DESCRIPTION
      :type:  str
      :value: 'Merge the type-rich information from a doc-stub into a firmware stub'



   .. py:attribute:: copy_params
      :type:  bool
      :value: True



   .. py:attribute:: copy_docstr
      :type:  bool
      :value: True



   .. py:attribute:: copy_returns
      :type:  bool
      :value: False



   .. py:method:: add_args(arg_parser: argparse.ArgumentParser) -> None
      :staticmethod:


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



   .. py:attribute:: replace_functiondef_with_classdef
      :value: True



   .. py:attribute:: stack
      :type:  List[str]
      :value: []



   .. py:attribute:: docstub_path


   .. py:attribute:: docstub_source


   .. py:attribute:: annotations
      :type:  Dict[Tuple[str, Ellipsis], stubber.typing_collector.AnnoValue]


   .. py:attribute:: comments
      :type:  List[str]
      :value: []



   .. py:attribute:: stub_imports
      :type:  Dict[str, libcst.codemod.visitors.ImportItem]


   .. py:attribute:: all_imports
      :type:  List[Union[libcst.Import, libcst.ImportFrom]]
      :value: []



   .. py:attribute:: type_helpers


   .. py:method:: 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.

      :param original_node: The original module node.
      :param updated_node: The updated module node after processing.
      :return: The updated module node.



   .. py:method:: add_missed_overloads(updated_node: Mod_Class_T, stack_id: tuple) -> Mod_Class_T

      Add any missing overloads to the updated_node




   .. py:method:: add_missed_mp_available(updated_node: Mod_Class_T, stack_id: tuple) -> Mod_Class_T

      Add any missing @mp_available to the updated_node




   .. py:method:: add_missed_literal_docstrings(updated_node: Mod_Class_T, stack_id: tuple) -> Mod_Class_T

      Add any missing literal docstrings to the updated_node



   .. py:method:: locate_function_by_name(overload, updated_body)

      locate the (last) function or class by name



   .. py:method:: visit_ClassDef(node: libcst.ClassDef) -> Optional[bool]

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



   .. py:method:: leave_ClassDef(original_node: libcst.ClassDef, updated_node: libcst.ClassDef) -> libcst.ClassDef


   .. py:method:: visit_FunctionDef(node: libcst.FunctionDef) -> Optional[bool]


   .. py:method:: leave_FunctionDef(original_node: libcst.FunctionDef, updated_node: libcst.FunctionDef) -> Union[libcst.FunctionDef, libcst.ClassDef]

      Update the function Parameters and return type, decorators and docstring



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