stubber: add enrich option to enhance docstub generation with type information

Signed-off-by: Jos Verlinde <[email protected]>

Author: Josverl

WIP.md

@@ -6,16 +6,22 @@
         - [ ] pypi 
 - [x] Test v1.23.0 stubs with new stdib ( avoid regressions )
         - [x] do the same for v1.24.1 stubs
-        - [ ] If needed publish update to v1.23.0 stubs to only allow stdlib v1.23.x
+        - [?] If needed publish update to v1.23.0 stubs to only allow stdlib v1.23.x
 
-- [ ] Update install example in stubs readme for v1.24.*     
 - [x] some decorators are added multiple times - need to check for existing decorator 
-- [ ] docstubs : should automagically enrich the docstubs
+- [x] docstubs : should automagically `--enrich` the docstubs on v1.24.1 and newer ( + CI) 
+    - [ ] publish stubber
+
+
 
 - [x] `__call__` needs addational overloads in machine and pyb modules 
-- [ ] stdlib/udate.py should use same config as stubber / merge_config 
-- [ ] stdlib/udate.py should allow configuration of version  
+- [x] stdlib/udate.py should allow configuration of version  
+- [ ] stdlib/udate.py should use same config as stubber 
+    - [x] uses config / pyproject.toml
+    - [ ] uses merge_config 
 
+
+- [ ] Update install example in stubs readme for v1.24.*     
 - [ ] Update the documentation for this.
         - MyPy change
         - how to install  
@@ -36,6 +42,10 @@
 
 
 # Longer term things to fix 
+ - [ ] generate badges for the stubs 
+        https://github.com/python/typing/discussions/1391
+        ![PyPI - Types](https://img.shields.io/pypi/types/micropython-esp32-stubs?style=plastic&label=esp32%20generic-S3)
+
 
 ## pyright: 
 

src/stubber/commands/get_docstubs_cmd.py

@@ -5,11 +5,13 @@
 
 from pathlib import Path
 from typing import Optional
+from packaging.version import Version
 
 import mpflash.basicgit as git
 import rich_click as click
 from mpflash.logger import log
 
+from stubber.codemod.enrich import enrich_folder
 import stubber.utils as utils
 from stubber.commands.cli import stubber_cli
 from stubber.stubs_from_docs import generate_from_rst
@@ -59,6 +61,13 @@
     help="remove .rST constructs from the docstrings",
     show_default=True,
 )
+@click.option(
+    "--enrich",
+    is_flag=True,
+    default=False,
+    help="Enrich with type information from micropython-reference",
+    show_default=True,
+)
 @click.pass_context
 def cli_docstubs(
     ctx: click.Context,
@@ -69,6 +78,7 @@ def cli_docstubs(
     clean_rst: bool = True,
     basename: Optional[str] = None,
     version: str = "",
+    enrich: bool = False,
 ):
     """
     Build stubs from documentation.
@@ -113,4 +123,24 @@ def cli_docstubs(
         autoflake=autoflake,
         clean_rst=clean_rst,
     )
+
+    if enrich:
+        if Version(version) < Version("1.24"):
+            log.warning(f"Enriching is not supported for version {version}")
+        else:
+            # !stubber enrich --params-only --source {reference} --dest {docstubs}
+            reference_path = CONFIG.stub_path.parent / "micropython-reference"
+            log.info(f"Enriching from {reference_path}")
+            _ = enrich_folder(
+                reference_path,
+                dst_path,
+                show_diff=False,
+                write_back=True,
+                require_docstub=False,
+                params_only=True,
+            )
+            log.info("::group:: start post processing of retrieved stubs")
+            # do not run stubgen
+            utils.do_post_processing([dst_path], stubgen=False, black=black, autoflake=autoflake)
+
     log.info("::group:: Done")