stubber.codemod.enrich
======================

.. py:module:: stubber.codemod.enrich

.. autoapi-nested-parse::

   Enrich firmware stubs by copying docstrings and parameter information from doc-stubs or python source code.
   Both (.py or .pyi) files are supported.



Classes
-------

.. autoapisummary::

   stubber.codemod.enrich.MergeMatch


Functions
---------

.. autoapisummary::

   stubber.codemod.enrich.package_from_path
   stubber.codemod.enrich.upackage_equal
   stubber.codemod.enrich.source_target_candidates
   stubber.codemod.enrich.enrich_file
   stubber.codemod.enrich.merge_candidates
   stubber.codemod.enrich.enrich_folder
   stubber.codemod.enrich.guess_port_from_path


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

.. py:class:: MergeMatch

   A match between a target and source file to merge docstrings and typehints


   .. py:attribute:: target
      :type:  pathlib.Path


   .. py:attribute:: source
      :type:  pathlib.Path


   .. py:attribute:: target_pkg
      :type:  str


   .. py:attribute:: source_pkg
      :type:  str


   .. py:attribute:: is_match
      :type:  bool


.. py:function:: package_from_path(target: pathlib.Path, source: Optional[pathlib.Path] = None) -> str

   Given a target and source path, return the package name based on the path.


.. py:function:: upackage_equal(src: str, target: str) -> Tuple[bool, int]

   Compare package names, return True if they are equal, ignoring an _ or u-prefix and case


.. py:function:: source_target_candidates(source: pathlib.Path, target: pathlib.Path, ext: Optional[str] = None) -> collections.abc.Generator[MergeMatch, None, None]

   Given a target and source path, return a list of tuples of `(target, source, package name)` that are candidates for merging.
   Goal is to match the target and source files based on the package name, to avoid mismatched merges of docstrings and typehints

   Returns a generator of tuples of `(target, source, target_package, source_package, is_partial_match)`


.. py:function:: enrich_file(source_path: pathlib.Path, target_path: pathlib.Path, diff: bool = False, write_back: bool = False, copy_params: bool = False, copy_docstr: bool = False, copy_returns: bool = False) -> collections.abc.Generator[str, None, None]

   Enrich firmware stubs using the doc-stubs in another folder.
   Both (.py or .pyi) files are supported.
   Both source an target files must exist, and are assumed to match.
   Any matching of source and target files should be done before calling this function.

   :param source_path: the  path to the firmware stub-file to enrich
   :param docstub_path: the path to the file  containing the doc-stubs
   :param diff: if True, return the diff between the original and the enriched source file
   :param write_back: if True, write the enriched source file back to the source_path

   Returns:
   - None or a string containing the diff between the original and the enriched source file


.. py:function:: merge_candidates(source_folder: pathlib.Path, target_folder: pathlib.Path) -> List[MergeMatch]

   Generate a list of merge candidates for the source and target folders.
   Each target is matched with exactly one source file.


.. py:function:: enrich_folder(source_folder: pathlib.Path, target_folder: pathlib.Path, show_diff: bool = False, write_back: bool = False, require_docstub: bool = False, copy_params: bool = False, ext: Optional[str] = None, copy_docstr: bool = False, copy_returns: bool = False) -> int

   Enrich a folder containing firmware stubs using the doc-stubs in another folder.

   Returns the number of files enriched.


.. py:function:: guess_port_from_path(folder: pathlib.Path) -> str

   Guess the port name from the folder contents.
   ( could also be done based on the path name)