Setup CLI and include implicit first command arguments

Author: Muream

README.md

@@ -8,9 +8,9 @@ This is not a small feat so the stubs will improve over time.
 - 🚧 maya.cmds: Incomplete
     - [x] Stubs for all commands.
     - [x] Accurate Arguments signatures for most commands (parsed from `cmds.help("command")`).
+    - [x] Implicit first argument(s) for most command.
     - [ ] Accurate Arguments signatures all commands.
-    - [ ] Implicit first argument of some commands.
     - [ ] Return Types.
     - [ ] Docstrings.
-- 🚫 OpenMaya 1.0: Missing
-- 🚫 OpenMaya 2.0: Missing
+- ❌ OpenMaya 1.0: Missing
+- ❌ OpenMaya 2.0: Missing

maya-stubs/cmds/__init__.pyi

@@ -0,0 +1,4 @@
+from ._cli import cli
+
+if __name__ == "__main__":
+    cli()

maya_stubgen/__main__.py

@@ -0,0 +1,36 @@
+import logging
+
+import click
+
+from maya_stubgen.get_cmds_synopsis import get_cmds_synopsis
+
+from .generate_stubs import generate_stubs
+from .utils import initialize_maya, uninitialize_maya
+
+logger = logging.getLogger("maya_stubgen")
+
+
+@click.group
+def cli():
+    initialize_maya()
+
+
+@cli.result_callback()
+def result(result):
+    uninitialize_maya()
+
+
+@cli.command
+def test_log():
+    logger.setLevel(logging.DEBUG)
+
+    logger.debug("Debug")
+    logger.info("Info")
+    logger.success("Success")
+    logger.warning("Warning")
+    logger.error("Error")
+    logger.critical("Critical")
+
+
+cli.add_command(generate_stubs)
+cli.add_command(get_cmds_synopsis)

maya_stubgen/_cli.py

@@ -2,29 +2,18 @@
 import keyword
 import logging
 import re
-import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from textwrap import indent
 from typing import *
 from typing import Callable
 
+import click
+
 logger = logging.getLogger(__name__)
-logger.setLevel(logging.INFO)
 
 DEBUG = False
 
-if __name__ == "__main__":
-    import maya.standalone
-
-    try:
-        logger.info("Initializing Maya Standalone.")
-        maya.standalone.initialize()
-    except BaseException:
-        logger.info("Failed to initialize Maya Standalone.")
-    else:
-        logger.info("Initialized Maya Standalone Successfully.")
-
 
 from maya import cmds
 
@@ -137,43 +126,86 @@ def cmds_functions() -> List[Callable]:
     return inspect.getmembers(cmds, callable)
 
 
-def _args_from_docstring(docstring: str) -> List[Argument]:
-    if "No Flags" in docstring:
+def _args_from_help(synopsis: str) -> List[Argument]:
+    if "No Flags" in synopsis:
         arguments = []
-    elif "Quick help is not available" in docstring:
+    elif "Quick help is not available" in synopsis:
         arguments = ["*args", "**kwargs"]
     else:
         arguments = []
-        types_regex = (
-            r"(\s+((?P<types>[\w\|]+( \w+)?)) ?(?P<multi_use>\(multi-use\))?)?$"
+
+        # https://regex101.com/r/9595nC/1
+        header_regex = r"Synopsis: (?P<name>\w+)( \[flags\] ?(?P<implicit_args>.*))?"
+
+        # https://regex101.com/r/bBZoCh/3
+        flag_regex = (
+            r"-(?P<short_name>\w+)\s+"
+            r"-(?P<long_name>\w+)"
+            r"(?P<types>[\w\|\s\[\]]+)?\s?"
+            r"(?P<multi_use>\(multi-use\))?\s?"
+            r"(\(Query Arg (?P<query_arg_mandatory>Mandatory|Optional)\))?"
         )
-        flag_regex = r"^-(?P<short_name>\w+)\s+-(?P<long_name>\S+)" + types_regex
-        for line in docstring.splitlines():
+
+        for line in synopsis.splitlines():
             line = line.strip()
-            match = re.match(flag_regex, line)
-            if match:
-                long_name = match["long_name"]
-                short_name = match["short_name"]
+
+            match_header = re.match(header_regex, line)
+            if match_header:
+                implicit_args = match_header["implicit_args"]
+
+                if not implicit_args:
+                    continue
+
+                implicit_args = implicit_args.strip()
+
+                if "..." in implicit_args:
+                    # the type is a list. Eg [String...]
+                    implicit_args = implicit_args[1:-1].replace("...", "")
+                    list_type = mel_to_python_type(implicit_args)
+                    arg_type = f"List[{list_type}]"
+                    arg_name = "*args"
+                elif implicit_args.count(" ") > 0:
+                    # the type is a tuple
+                    implicit_args = implicit_args.replace("[", "").replace("]", "")
+                    tuple_types = map(mel_to_python_type, implicit_args.split())
+                    arg_type = f"Tuple[{', '.join(tuple_types)}]"
+                    arg_name = "*args"
+                else:
+                    # the type is a basic type
+                    arg_type = mel_to_python_type(implicit_args)
+                    arg_name = "arg0"
+
+                argument = Argument(arg_name, None, arg_type)
+                arguments.append(argument)
+
+                continue
+
+            match_flag = re.match(flag_regex, line)
+            if match_flag:
+                long_name = match_flag["long_name"]
+                short_name = match_flag["short_name"]
 
                 # types can be either
                 # - One type. eg: Float
                 # - Multiple types. eg: Float String Int
+                # - Union of types?. eg: [Float on|off]  # TODO: Unsupported
                 # - None (when no type is specified).
-                types = str(match["types"]).split()
+                types = str(match_flag["types"]).split()
                 types = [mel_to_python_type(t) for t in types]
 
                 if len(types) == 1:
-                    type_ = types[0]
+                    arg_type = types[0]
                 else:
-                    type_ = f"Tuple[{', '.join(types)}]"
+                    arg_type = f"Tuple[{', '.join(types)}]"
 
-                multi_use = match["multi_use"]
+                multi_use = match_flag["multi_use"]
                 if multi_use:
-                    type_ = f"List[{type_}]"
+                    arg_type = f"List[{arg_type}]"
 
-                argument = Argument(long_name, short_name, type_)
+                argument = Argument(long_name, short_name, arg_type)
                 if argument not in arguments:
                     arguments.append(argument)
+                continue
 
     return arguments
 
@@ -200,6 +232,8 @@ def mel_to_python_type(type: str) -> str:
         "UnsignedInt": "int",
         "Time": "int",
         # bool
+        "": "bool",
+        None: "bool",
         "None": "bool",
         "on|off": "bool",
     }
@@ -217,52 +251,40 @@ def generate_stubs_content() -> str:
     for func, _ in cmds_functions():
         logger.debug("Generating signature for %s", func)
         try:
-            docstring = cmds.help(func).strip("\n")
+            help = cmds.help(func).strip("\n")
         except RuntimeError:
-            docstring = ""
+            help = ""
 
-        args = _args_from_docstring(docstring)
+        args = _args_from_help(help)
 
-        function = Function(func, arguments=args, docstring=docstring)
+        function = Function(func, arguments=args, docstring=help)
         lines.append(function.stub)
 
     return "\n".join(lines)
 
 
 def write_stubs(stubs: str) -> None:
     stubs_path = Path(__file__).parent.parent / "maya-stubs" / "cmds" / "__init__.pyi"
+
     logger.debug("Writing stubs in %s", stubs_path)
+
     stubs_path.parent.mkdir(parents=True, exist_ok=True)
 
     with stubs_path.open("w") as f:
         f.write(stubs)
 
+    return stubs_path
 
+
+@click.command()
 def generate_stubs() -> None:
     logger.info("Generating Stubs")
 
-    stubs = generate_stubs_content()
-    write_stubs(stubs)
-
-    logger.info("Stubs Generated Successfully")
-
-
-def main():
-    global DEBUG
-    DEBUG = "--debug" in sys.argv
-
-    generate_stubs()
-
-
-if __name__ == "__main__":
-    main()
-
-    import maya.standalone
-
     try:
-        logger.info("Uninitializing Maya Standalone.")
-        maya.standalone.uninitialize()
-    except BaseException:
-        logger.info("Failed to uninitialize Maya Standalone.")
+        stubs = generate_stubs_content()
+        stubs_path = write_stubs(stubs)
+    except BaseException as e:
+        logger.error("Failed to generate stubs")
+        raise e
     else:
-        logger.info("Uninitialized Maya Standalone Successfully.")
+        logger.success("Stubs generated in %s", stubs_path)

scripts/generate_stubs.py maya_stubgen/generate_stubs.pyscripts/generate_stubs.py renamed to maya_stubgen/generate_stubs.py

@@ -0,0 +1,81 @@
+import inspect
+import logging
+from enum import Enum
+from pathlib import Path
+from typing import *
+
+import click
+from maya import cmds
+
+logger = logging.Logger(__name__)
+
+
+class SynopsisType(Enum):
+    all = "all"
+    synopsis = "synopsis"
+    flags = "flags"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+def cmds_functions() -> List[Callable]:
+    return inspect.getmembers(cmds, callable)
+
+
+def synopsis_for_type(type: SynopsisType):
+    logger.info("Generating Synopsis for type : %s", type)
+    all_lines = []
+
+    include_synopsis = type is type is SynopsisType.all or type is SynopsisType.synopsis
+    include_flags = type is type is SynopsisType.all or type is SynopsisType.flags
+
+    for func, _ in cmds_functions():
+        try:
+            doc = cmds.help(func)
+        except RuntimeError:
+            pass
+        else:
+            lines = []
+
+            synopsis = f"Synopsis: {func}"
+
+            for line in doc.splitlines():
+                line = line.strip()
+
+                if "Synopsis" in line:
+                    synopsis = line
+
+                if line.startswith("-"):
+                    if include_flags:
+                        lines.append(line)
+
+            if type is SynopsisType.all:
+                synopsis = f"\n{synopsis}"
+
+            if include_synopsis:
+                lines.insert(0, synopsis)
+
+        all_lines.extend(lines)
+
+    return "\n".join(all_lines).strip()
+
+
+@click.command
+@click.option(
+    "--type",
+    default=SynopsisType.all.value,
+    type=click.Choice(SynopsisType.__members__),
+)
+def get_cmds_synopsis(type):
+
+    type = SynopsisType(type)
+    cmds_synopsis = synopsis_for_type(type)
+
+    out_file = Path() / "out" / "synopsis" / f"{type}.txt"
+    out_file.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(out_file, "w") as f:
+        f.write(cmds_synopsis)
+
+    logger.success("Generated synopsis: %s", out_file)

maya_stubgen/get_cmds_synopsis.py

@@ -0,0 +1,40 @@
+import logging
+from contextlib import contextmanager
+from typing import *
+
+logger = logging.getLogger(__name__)
+
+
+def initialize_maya():
+    logger.info("Initializing Maya Standalone")
+    try:
+        import maya.standalone
+
+        logging.getLogger().handlers
+
+        maya.standalone.initialize()
+    except BaseException:
+        logger.error("Failed to initialize Maya Standalone")
+    else:
+        # remove maya's handler
+        logging.getLogger().handlers.pop()
+        logger.success("Maya Standalone Initialized")
+
+
+def uninitialize_maya():
+    logger.info("Uninitializing Maya Standalone")
+    try:
+        import maya.standalone
+
+        maya.standalone.uninitialize()
+    except BaseException:
+        logger.error("Failed to uninitialize Maya Standalone")
+    else:
+        logger.success("Maya Standalone Uninitialized")
+
+
+@contextmanager
+def maya_standalone():
+    initialize_maya()
+    yield
+    uninitialize_maya()