Replace argparse with typer for WRITEME flags. (#7252)

Author: DavidSouther

.tools/readmes/README.md

@@ -16,10 +16,10 @@ cd .tools/readmes
 python -m venv .venv
 
 # Windows
-.venv\Scripts\activate 
+.venv\Scripts\activate
 
 # Linux or MacOS
-source .venv/bin/activate 
+source .venv/bin/activate
 ```
 
 Depending on how you have Python installed and on your operating system,
@@ -60,7 +60,7 @@ This creates a README.md file in the `python/example_code/s3` folder.
 - `--dry-run`, `--no-dry-run` In dry run, compare current vs generated and exit with failure if they do not match.
 - `--check` Verifies whether the existing README.md matches the proposed new README.md
   (but does not write a new README.md). This is the same check that is run by the GitHub action.
- 
+
 You can get inline usage info by using the `-h` flag:
 
 ```

.tools/readmes/requirements.txt

@@ -1,3 +1,4 @@
 jinja2>=3.0.3
 pyyaml>=5.3.1
+typer==0.15.1
 aws-doc-sdk-examples-tools @ git+https://github.com/awsdocs/aws-doc-sdk-examples-tools

.tools/readmes/requirements_freeze.txt

@@ -0,0 +1,32 @@
+aws_doc_sdk_examples_tools @ git+https://github.com/awsdocs/[email protected]
+black==24.3.0
+certifi==2025.1.31
+charset-normalizer==3.4.1
+click==8.1.8
+flake8==6.1.0
+idna==3.10
+iniconfig==2.0.0
+Jinja2==3.1.4
+markdown-it-py==3.0.0
+MarkupSafe==3.0.2
+mccabe==0.7.0
+mdurl==0.1.2
+mypy==1.8.0
+mypy-extensions==1.0.0
+packaging==24.2
+pathspec==0.11.2
+platformdirs==4.3.6
+pluggy==1.5.0
+pycodestyle==2.11.1
+pyflakes==3.1.0
+Pygments==2.19.1
+pytest==8.0.0
+PyYAML==6.0.1
+requests==2.32.0
+rich==13.9.4
+shellingham==1.5.4
+typer==0.15.1
+types-PyYAML==6.0.12.12
+typing_extensions==4.12.2
+urllib3==2.3.0
+yamale==4.0.4

.tools/readmes/runner.py

@@ -1,19 +1,28 @@
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-import argparse
-import config
+import typer
+from typing_extensions import Annotated
 import logging
 import os
+
 from difflib import unified_diff
+from enum import Enum
 from pathlib import Path
 from typing import Optional
 
-from render import Renderer, MissingMetadataError, RenderStatus
+from render import Renderer, RenderStatus, MissingMetadataError
 from scanner import Scanner
 
 from aws_doc_sdk_examples_tools.doc_gen import DocGen
 
+
+# Default to not using Rich
+if "USE_RICH" not in os.environ:
+    import typer.core
+
+    typer.core.rich = None  # type: ignore
+
 logging.basicConfig(level=os.environ.get("LOGLEVEL", "INFO").upper(), force=True)
 
 
@@ -35,61 +44,70 @@ def prepare_scanner(doc_gen: DocGen) -> Optional[Scanner]:
     return scanner
 
 
-def main():
-    # Load all examples immediately for cross references. Trades correctness for speed.
-    doc_gen = DocGen.from_root(Path(__file__).parent.parent.parent, incremental=True)
-
-    languages = doc_gen.languages()
-    parser = argparse.ArgumentParser()
-    parser.add_argument(
-        "--languages",
-        choices=[*languages] + ["all"],
-        nargs="+",
-        help="The languages of the SDK. Choose from: %(choices)s.",
-        default=["all"],
-    )
-
-    parser.add_argument(
-        "--services",
-        choices=[*doc_gen.services.keys()] + ["all"],
-        nargs="+",
-        help="The targeted service. Choose from: %(choices)s.",
-        default=["all"],
-    )
-    parser.add_argument(
-        "--safe",
-        action="store_true",
-        help=f"Save a copy of the original README as the 'saved_readme' value specified in config.py ({config.saved_readme}).",
-    )
-    parser.add_argument(
-        "--verbose",
-        action="store_true",
-        help="When set, output verbose debugging info.",
-    )
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        dest="dry_run",
-        help="In dry run, compare current vs generated and exit with failure if they do not match.",
-        default=False,  # Change this to default false when we're ready to use this generally.
-    )
-    parser.add_argument("--no-dry-run", dest="dry_run", action="store_false")
-    parser.add_argument("--check", dest="dry_run", action="store_true")
-    parser.add_argument("--diff", action="store_true", default=False)
-    args = parser.parse_args()
-
-    if "all" in args.languages:
-        args.languages = [*languages]
-
-    if "all" in args.services:
-        args.services = [*doc_gen.services.keys()]
-
-    if args.verbose:
+# Load all examples immediately for cross references. Trades correctness for speed.
+doc_gen = DocGen.from_root(Path(__file__).parent.parent.parent, incremental=True)
+
+
+Language = Enum(
+    "Language", {lang: lang for lang in ([*doc_gen.languages()] + ["all"])}
+)  # type: ignore
+Service = Enum(
+    "Service", {serv: serv for serv in ([*doc_gen.services.keys()] + ["all"])}
+)  # type: ignore
+
+
+def writeme(
+    languages: Annotated[
+        list[Language],  # type: ignore
+        typer.Option(
+            help="The languages of the SDK.",
+        ),
+    ] = [
+        Language.all.value  # type: ignore
+    ],  # type: ignore
+    services: Annotated[
+        list[Service],  # type: ignore
+        typer.Option(
+            help="The targeted service.",
+        ),
+    ] = [
+        Service.all.value  # type: ignore
+    ],  # type: ignore
+    safe: Annotated[
+        bool,
+        typer.Option(
+            help="Save a copy of the original README as the 'saved_readme' value specified in config.py ({config.saved_readme})."
+        ),
+    ] = True,
+    verbose: Annotated[
+        bool, typer.Option(help="When set, output verbose debugging info.")
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="In dry run, compare current vs generated and exit with failure if they do not match."
+        ),
+    ] = False,
+    check: Annotated[bool, typer.Option(help="Alias for --dry-run.")] = False,
+    diff: Annotated[
+        bool, typer.Option(help="Show a diff of READMEs that have changed.")
+    ] = False,
+):
+    if Language.all in languages:  # type: ignore
+        languages = list(Language)  # type: ignore
+        languages.remove(Language.all)  # type: ignore
+
+    if Service.all in services:  # type: ignore
+        services = list(Service)  # type: ignore
+        services.remove(Service.all)  # type: ignore
+
+    if verbose:
         logging.basicConfig(level=logging.DEBUG)
 
-    logging.debug(f"Args configuration: {args}")
+    if check:
+        dry_run = check
 
-    if args.dry_run:
+    if dry_run:
         print("Dry run, no changes will be made.")
 
     skipped = []
@@ -104,23 +122,27 @@ def main():
         return -1
 
     renderer = Renderer(scanner)
-    for service in args.services:
-        for language_and_version in args.languages:
-            (language, version) = language_and_version.split(":")
+    for service in services:
+        if service == Service.all:  # type: ignore
+            continue
+        for language_and_version in languages:
+            if language_and_version == Language.all:  # type: ignore
+                continue
+            (language, version) = language_and_version.value.split(":")
             id = f"{language}:{version}:{service}"
             try:
-                renderer.set_example(service, language, int(version), args.safe)
+                renderer.set_example(service.value, language, int(version), safe)
 
                 logging.debug("Rendering %s", id)
                 render_status = renderer.render()
                 logging.debug("Status %s", render_status)
 
                 if render_status == RenderStatus.UPDATED:
-                    if args.dry_run:
-                        diff = None
-                        if args.diff:
-                            diff = make_diff(renderer, id)
-                        failed.append((id, diff))
+                    if dry_run:
+                        diff_text = None
+                        if diff:
+                            diff_text = make_diff(renderer, id)
+                        failed.append((id, diff_text))
                     else:
                         renderer.write()
                         written.append(id)
@@ -139,10 +161,10 @@ def main():
                 skipped.append(id)
             except MissingMetadataError as mme:
                 logging.debug(mme, exc_info=True)
-                failed.append(id)
+                failed.append((id, None))
             except Exception as e:
                 logging.error(e, exc_info=True)
-                failed.append(id)
+                failed.append((id, None))
 
     skip_list = "\n".join(f"Skipped {f}" for f in sorted(skipped))
     logging.debug(skip_list or "(None Skipped)")
@@ -155,11 +177,11 @@ def main():
     if no_folder:
         no_folder_list = "\n".join(f"No folder: {f}" for f in sorted(no_folder))
         print(no_folder_list)
-    if not args.dry_run:
+    if not dry_run:
         done_list = "\n".join(f"Wrote {f}" for f in sorted(written))
         print(done_list or "(None Written)")
     if failed:
-        if args.diff:
+        if diff:
             failed_list = "\n".join(
                 f"Diff: {f[1]}" for f in sorted(failed, key=lambda f: f[0])
             )

.tools/readmes/writeme.py

@@ -2,25 +2,30 @@
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-import sys
-
-from update import update
-
 # For debugging, engineers can skip update with the --no-update flag. Yes, it's
 # a double negative, but it's quick and early in the startup because of the
 # reliance on the side-effect imports from `update` and needing them to happen
 # before importing runner, which means before importing the runner argparser.
 NO_UPDATE_FLAG = "--no-update"
 
-
 if __name__ == "__main__":
+    import sys
+
     if NO_UPDATE_FLAG not in sys.argv:
+        from update import update
+
         update()
     else:
         sys.argv.remove(NO_UPDATE_FLAG)
 
-    # This import must remain in the main, after the update, as it depends on
-    # importing the things that got changed during update.
-    from runner import main
+    # This import from runner must remain in __main__, after calling update(),
+    # as it depends on things that got changed during update().
+    from runner import writeme
+
+    from typer import run
+
+    run(writeme)
+else:
+    from .runner import writeme
 
-    sys.exit(main())
+    main = writeme