chore: standardize CLI nomenclature, aliases, arguments and programmatic API

This commit consolidates recent changes to standardize CLI docstrings,
arguments, secondary flags, operations, and the programmatic SDK API
per the consistency plan.

Author: SamuelMarks

README.md

@@ -3,7 +3,7 @@ cdd-python-all
 [![License](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![interactive WASM web demo](https://img.shields.io/badge/interactive-WASM_web_demo-blue.svg)](https://offscale.io/wasm_web_demo)
 [![CI](https://github.com/offscale/cdd-python-all/actions/workflows/ci.yml/badge.svg)](https://github.com/offscale/cdd-python-all/actions)
-[![Test Coverage](https://img.shields.io/badge/test_coverage-100%25-brightgreen.svg)](#)
+[![Test Coverage](https://img.shields.io/badge/test_coverage-99%25-brightgreen.svg)](#)
 [![Doc Coverage](https://img.shields.io/badge/doc_coverage-100%25-brightgreen.svg)](#)
 
 ----

alpine.Dockerfile

@@ -22,4 +22,4 @@ COPY --from=builder /app/dist/*.whl ./
 RUN pip install --no-cache-dir ./*.whl
 
 EXPOSE 8080
-ENTRYPOINT ["cdd-python", "server_json_rpc", "--listen", "0.0.0.0", "--port", "8080"]
+ENTRYPOINT ["cdd-python", "serve_json_rpc", "--listen", "0.0.0.0", "--port", "8080"]

debian.Dockerfile

@@ -22,4 +22,4 @@ COPY --from=builder /app/dist/*.whl ./
 RUN pip install --no-cache-dir ./*.whl
 
 EXPOSE 8080
-ENTRYPOINT ["cdd-python", "server_json_rpc", "--listen", "0.0.0.0", "--port", "8080"]
+ENTRYPOINT ["cdd-python", "serve_json_rpc", "--listen", "0.0.0.0", "--port", "8080"]

src/openapi_client/__init__.py

@@ -5,5 +5,19 @@
 from openapi_client.routes.emit import ClientGenerator
 from openapi_client.routes.parse import extract_from_code
 from openapi_client.models import OpenAPI
+from openapi_client.sdk import (
+    generate_from_openapi,
+    generate_to_openapi,
+    generate_docs_json,
+    serve_json_rpc,
+)
 
-__all__ = ["ClientGenerator", "extract_from_code", "OpenAPI"]
+__all__ = [
+    "ClientGenerator",
+    "extract_from_code",
+    "OpenAPI",
+    "generate_from_openapi",
+    "generate_to_openapi",
+    "generate_docs_json",
+    "serve_json_rpc",
+]

src/openapi_client/cli.py

@@ -30,9 +30,7 @@ def get_version() -> str:
         return "0.0.1"
 
 
-def apply_env_vars_to_parser(
-    parser: argparse.ArgumentParser, prefix: str = "CDD_PYTHON_"
-):
+def apply_env_vars_to_parser(parser: argparse.ArgumentParser, prefix: str = "CDD_"):
     """Recursively set argparse default values from environment variables."""
     for action in parser._actions:
         if action.dest and action.dest != "help" and action.dest != "==SUPPRESS==":
@@ -208,7 +206,7 @@ def scaffold_github_actions(out_dir: Path, tests: bool = False):
         )
 
 
-def process_from_openapi(
+def generate_from_openapi(
     subcommand: str,
     input_path: str,
     input_dir: str,
@@ -333,7 +331,7 @@ def process_from_openapi(
     print(f"Successfully generated {subcommand} in {out_dir}")
 
 
-def sync_to_openapi(input_path: str, output_path: str) -> None:
+def generate_to_openapi(input_path: str, output_path: str) -> None:
     """Extract an OpenAPI spec from a Python module or directory."""
     if not output_path:
         output_path = "openapi.json"
@@ -533,7 +531,7 @@ def sync_dir(project_dir: str) -> None:
     print(f"Successfully synced {project_dir}")
 
 
-def run_json_rpc_server(port: int, listen: str):
+def serve_json_rpc(port: int, listen: str):
     """Run a JSON-RPC 2.0 server exposing the CLI subcommands."""
     from http.server import BaseHTTPRequestHandler, HTTPServer
     import traceback
@@ -565,11 +563,16 @@ def do_POST(self):
 
             try:
                 if method == "to_openapi":
-                    sync_to_openapi(params.get("file"), params.get("output"))
+                    generate_to_openapi(params.get("input"), params.get("output"))
                     result = "Success"
-                elif method == "from_openapi":
-                    process_from_openapi(
-                        params.get("subcommand"),
+                elif method in (
+                    "from_openapi_to_sdk",
+                    "from_openapi_to_sdk_cli",
+                    "from_openapi_to_server",
+                ):
+                    subcommand = method.replace("from_openapi_", "")
+                    generate_from_openapi(
+                        subcommand,
                         params.get("input"),
                         params.get("input_dir"),
                         params.get("output"),
@@ -628,31 +631,33 @@ def main() -> None:
     subparsers = parser.add_subparsers(dest="command")
 
     from_openapi_parser = subparsers.add_parser(
-        "from_openapi", help="Generate code from OpenAPI"
+        "from_openapi", help="Generate code from an OpenAPI specification."
     )
 
     group = from_openapi_parser.add_mutually_exclusive_group(required=False)
-    group.add_argument("-i", "--input", type=str, help="Path to OpenAPI JSON file")
     group.add_argument(
-        "--input-dir", type=str, help="Directory containing OpenAPI specs"
+        "-i", "--input", type=str, help="Path or URL to the OpenAPI specification."
+    )
+    group.add_argument(
+        "--input-dir", type=str, help="Directory containing OpenAPI specifications."
     )
     from_openapi_parser.add_argument(
-        "-o", "--output", type=str, default=".", help="Output directory"
+        "-o", "--output", type=str, default=".", help="Output file or directory path."
     )
     from_openapi_parser.add_argument(
         "--no-github-actions",
         action="store_true",
-        help="Do not generate GitHub Actions",
+        help="Do not generate GitHub Actions scaffolding.",
     )
     from_openapi_parser.add_argument(
         "--no-installable-package",
         action="store_true",
-        help="Do not generate installable package scaffolding",
+        help="Do not generate installable package scaffolding.",
     )
     from_openapi_parser.add_argument(
         "--tests",
         action="store_true",
-        help="Create composable tests & mocks",
+        help="Generate integration tests and mocks.",
     )
 
     from_openapi_subparsers = from_openapi_parser.add_subparsers(
@@ -662,43 +667,51 @@ def main() -> None:
     for subcmd in ["to_sdk", "to_sdk_cli", "to_server"]:
         p = from_openapi_subparsers.add_parser(subcmd)
         group = p.add_mutually_exclusive_group(required=False)
-        group.add_argument("-i", "--input", type=str, help="Path to OpenAPI JSON file")
         group.add_argument(
-            "--input-dir", type=str, help="Directory containing OpenAPI specs"
+            "-i", "--input", type=str, help="Path or URL to the OpenAPI specification."
+        )
+        group.add_argument(
+            "--input-dir", type=str, help="Directory containing OpenAPI specifications."
+        )
+        p.add_argument(
+            "-o",
+            "--output",
+            type=str,
+            default=".",
+            help="Output file or directory path.",
         )
-        p.add_argument("-o", "--output", type=str, default=".", help="Output directory")
         p.add_argument(
             "--no-github-actions",
             action="store_true",
-            help="Do not generate GitHub Actions",
+            help="Do not generate GitHub Actions scaffolding.",
         )
         p.add_argument(
             "--no-installable-package",
             action="store_true",
-            help="Do not generate installable package scaffolding",
+            help="Do not generate installable package scaffolding.",
         )
         p.add_argument(
             "--tests",
             action="store_true",
-            help="Create composable tests & mocks",
+            help="Generate integration tests and mocks.",
         )
 
     to_openapi_parser = subparsers.add_parser(
-        "to_openapi", help="Extract OpenAPI from code"
+        "to_openapi", help="Generate an OpenAPI specification from source code."
     )
     to_openapi_parser.add_argument(
         "-i",
         "--input",
         type=str,
-        help="Path to Python source file or directory",
+        help="Path to source code directory or file",
         required=True,
     )
     to_openapi_parser.add_argument(
         "-o",
         "--output",
         type=str,
         default="openapi.json",
-        help="Output OpenAPI JSON file",
+        help="Output file or directory path",
     )
 
     sync_parser = subparsers.add_parser(
@@ -713,31 +726,34 @@ def main() -> None:
     )
 
     docs_parser = subparsers.add_parser(
-        "to_docs_json", help="Generate JSON documentation"
+        "to_docs_json",
+        help="Generate JSON documentation with code snippets for an OpenAPI specification.",
     )
     docs_parser.add_argument(
         "-i",
         "--input",
         type=str,
         required=True,
-        help="Path or URL to the OpenAPI specification",
+        help="Path or URL to the OpenAPI specification.",
     )
     docs_parser.add_argument(
-        "--no-imports", action="store_true", help="Omit the imports field"
+        "--no-imports", action="store_true", help="Omit the imports field."
     )
     docs_parser.add_argument(
-        "--no-wrapping", action="store_true", help="Omit the wrapper fields"
+        "--no-wrapping", action="store_true", help="Omit the wrapper fields."
     )
     docs_parser.add_argument(
-        "-o", "--output", type=str, help="Output JSON file (defaults to stdout)"
+        "-o", "--output", type=str, help="Output file or directory path."
     )
 
-    server_parser = subparsers.add_parser("server_json_rpc", help="Run JSON-RPC server")
+    server_parser = subparsers.add_parser(
+        "serve_json_rpc", help="Expose CLI interface as a JSON-RPC server."
+    )
     server_parser.add_argument(
-        "--port", type=int, default=8080, help="Port to listen on"
+        "-p", "--port", type=int, default=8080, help="Port to listen on"
     )
     server_parser.add_argument(
-        "--listen", type=str, default="0.0.0.0", help="Address to listen on"
+        "-l", "--listen", type=str, default="0.0.0.0", help="Address to listen on"
     )
 
     apply_env_vars_to_parser(parser)
@@ -754,7 +770,7 @@ def main() -> None:
         if not args.input and not getattr(args, "input_dir", None):
             from_openapi_parser.print_help()
             sys.exit(1)
-        process_from_openapi(
+        generate_from_openapi(
             subcmd,
             args.input,
             getattr(args, "input_dir", None),
@@ -765,11 +781,11 @@ def main() -> None:
         )
     elif args.command == "to_openapi":
         in_path = args.input
-        sync_to_openapi(in_path, args.output)
+        generate_to_openapi(in_path, args.output)
     elif args.command == "to_docs_json":
         generate_docs_json(args.input, args.no_imports, args.no_wrapping, args.output)
-    elif args.command == "server_json_rpc":
-        run_json_rpc_server(args.port, args.listen)
+    elif args.command == "serve_json_rpc":
+        serve_json_rpc(args.port, args.listen)
 
 
 if __name__ == "__main__":  # pragma: no cover

src/openapi_client/functions/utils.py

@@ -5,12 +5,18 @@
 import re
 
 
+def to_snake_case(name: str) -> str:
+    """Convert PascalCase or camelCase to snake_case."""
+    s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
+    return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+
 def sanitize_name(name: str) -> str:
-    """Sanitize a string to be a valid Python identifier."""
+    """Sanitize a string to be a valid Python identifier in snake_case."""
     if not name:
         return ""
     sanitized = re.sub(r"\W|^(?=\d)", "_", name)
-    return sanitized
+    return to_snake_case(sanitized)
 
 
 def get_annotation_for_schema(s) -> str:

src/openapi_client/sdk.py

@@ -0,0 +1,46 @@
+"""Programmatic SDK for cdd-python-all."""
+
+from typing import Optional
+from openapi_client.cli import generate_from_openapi as cli_generate_from_openapi
+from openapi_client.cli import generate_to_openapi as cli_generate_to_openapi
+from openapi_client.cli import generate_docs_json as cli_generate_docs_json
+from openapi_client.cli import serve_json_rpc as cli_serve_json_rpc
+
+
+def generate_from_openapi(
+    input_path: str,
+    output_dir: str,
+    no_github_actions: bool = False,
+    no_installable_package: bool = False,
+    tests: bool = False,
+    subcommand: str = "to_sdk",
+) -> None:
+    """Generate code from an OpenAPI specification."""
+    cli_generate_from_openapi(
+        subcommand=subcommand,
+        input_path=input_path,
+        output_dir=output_dir,
+        no_github_actions=no_github_actions,
+        no_installable_package=no_installable_package,
+        tests=tests,
+    )
+
+
+def generate_to_openapi(input_dir: str, output_path: Optional[str] = None) -> None:
+    """Generate an OpenAPI specification from source code."""
+    cli_generate_to_openapi(input_dir, output_path)
+
+
+def generate_docs_json(
+    input_path: str,
+    no_imports: bool = False,
+    no_wrapping: bool = False,
+    output_path: Optional[str] = None,
+) -> None:
+    """Generate JSON documentation with code snippets for an OpenAPI specification."""
+    cli_generate_docs_json(input_path, no_imports, no_wrapping, output_path)
+
+
+def serve_json_rpc(port: int = 8080, listen: str = "127.0.0.1") -> None:
+    """Expose CLI interface as a JSON-RPC server."""
+    cli_serve_json_rpc(port, listen)