Implement command line interface

README.md

@@ -38,11 +38,12 @@ This project exists because I am unhappy with the state of the official Google p
   - Uses `SerializeToString()` rather than the built-in `__bytes__()`
   - Special wrapped types don't use Python's `None`
   - Timestamp/duration types don't use Python's built-in `datetime` module
+
 This project is a reimplementation from the ground up focused on idiomatic modern Python to help fix some of the above. While it may not be a 1:1 drop-in replacement due to changed method names and call patterns, the wire format is identical.
 
 ## Installation
 
-First, install the package. Note that the `[compiler]` feature flag tells it to install extra dependencies only needed by the `protoc` plugin:
+First, install the package. Note that the `[compiler]` feature flag tells it to install extra dependencies only needed by the code generator:
 
 ```sh
 # Install both the library and compiler
@@ -71,18 +72,10 @@ message Greeting {
 }
 ```
 
-You can run the following to invoke protoc directly:
+To compile the protobuf you would run the following:
 
 ```sh
-mkdir lib
-protoc -I . --python_betterproto_out=lib example.proto
-```
-
-or run the following to invoke protoc via grpcio-tools:
-
-```sh
-pip install grpcio-tools
-python -m grpc_tools.protoc -I . --python_betterproto_out=lib example.proto
+betterproto compile example.proto --output=lib
 ```
 
 This will generate `lib/hello/__init__.py` which looks like:
@@ -169,16 +162,13 @@ from grpclib.client import Channel
 
 
 async def main():
-    channel = Channel(host="127.0.0.1", port=50051)
-    service = echo.EchoStub(channel)
-    response = await service.echo(value="hello", extra_times=1)
-    print(response)
-
-    async for response in service.echo_stream(value="hello", extra_times=1):
-        print(response)
-
-    # don't forget to close the channel when done!
-    channel.close()
+    async with Channel(host="127.0.0.1", port=50051) as channel:
+      service = echo.EchoStub(channel)
+      response = await service.echo(value="hello", extra_times=1)
+      print(response)
+
+      async for response in service.echo_stream(value="hello", extra_times=1):
+          print(response)
 
 
 if __name__ == "__main__":
@@ -271,23 +261,23 @@ You can use `betterproto.which_one_of(message, group_name)` to determine which o
 ```py
 >>> test = Test()
 >>> betterproto.which_one_of(test, "foo")
-["", None]
+("", None)
 
 >>> test.on = True
 >>> betterproto.which_one_of(test, "foo")
-["on", True]
+("on", True)
 
 # Setting one member of the group resets the others.
 >>> test.count = 57
 >>> betterproto.which_one_of(test, "foo")
-["count", 57]
+("count", 57)
 >>> test.on
 False
 
 # Default (zero) values also work.
 >>> test.name = ""
 >>> betterproto.which_one_of(test, "foo")
-["name", ""]
+("name", "")
 >>> test.count
 0
 >>> test.on
@@ -303,7 +293,7 @@ Again this is a little different than the official Google code generator:
 
 # New way (this project)
 >>> betterproto.which_one_of(message, "group")
-["foo", "foo's value"]
+("foo", "foo's value")
 ```
 
 ### Well-Known Google Types
@@ -438,7 +428,7 @@ poe full-test
 Betterproto includes compiled versions for Google's well-known types at [betterproto/lib/google](betterproto/lib/google).
 Be sure to regenerate these files when modifying the plugin output format, and validate by running the tests.
 
-Normally, the plugin does not compile any references to `google.protobuf`, since they are pre-compiled. To force compilation of `google.protobuf`, use the option `--custom_opt=INCLUDE_GOOGLE`. 
+Normally, the plugin does not compile any references to `google.protobuf`, since they are pre-compiled. To force compilation of `google.protobuf`, use the option `--custom_opt=INCLUDE_GOOGLE`.
 
 Assuming your `google.protobuf` source files (included with all releases of `protoc`) are located in `/usr/local/include`, you can regenerate them as follows:
 

docs/migrating.rst

@@ -4,7 +4,7 @@ Migrating Guide
 Google's protocolbuffers
 ------------------------
 
-betterproto has a mostly 1 to 1 drop in replacement for Google's protocolbuffers (after
+betterproto has a mostly 1 to 1 drop in replacement for Google's protocol buffers (after
 regenerating your protobufs of course) although there are some minor differences.
 
 .. note::

docs/quick-start.rst

@@ -40,22 +40,11 @@ Given you installed the compiler and have a proto file, e.g ``example.proto``:
       string message = 1;
     }
 
-To compile the proto you would run the following:
-
-You can run the following to invoke protoc directly:
+To compile the protobuf you would run the following:
 
 .. code-block:: sh
 
-    mkdir hello
-    protoc -I . --python_betterproto_out=lib example.proto
-
-or run the following to invoke protoc via grpcio-tools:
-
-.. code-block:: sh
-
-    pip install grpcio-tools
-    python -m grpc_tools.protoc -I . --python_betterproto_out=lib example.proto
-
+    betterproto compile example.proto --output=lib
 
 This will generate ``lib/__init__.py`` which looks like:
 
@@ -141,16 +130,13 @@ The generated client can be used like so:
 
 
     async def main():
-        channel = Channel(host="127.0.0.1", port=50051)
-        service = echo.EchoStub(channel)
-        response = await service.echo(value="hello", extra_times=1)
-        print(response)
-
-        async for response in service.echo_stream(value="hello", extra_times=1):
+        async with Channel(host="127.0.0.1", port=50051) as channel:
+            service = echo.EchoStub(channel)
+            response = await service.echo(value="hello", extra_times=1)
             print(response)
 
-        # don't forget to close the channel when you're done!
-        channel.close()
+            async for response in service.echo_stream(value="hello", extra_times=1):
+                print(response)
 
     asyncio.run(main())  # python 3.7 only
 

pyproject.toml

@@ -17,6 +17,8 @@ black = { version = ">=19.3b0", optional = true }
 dataclasses = { version = "^0.7", python = ">=3.6, <3.7" }
 grpclib = "^0.4.1"
 jinja2 = { version = "^2.11.2", optional = true }
+typer = { version = "^0.3.2", optional = true }
+rich = { version = "^9.8.2", optional = true }
 python-dateutil = "^2.8"
 
 [tool.poetry.dev-dependencies]
@@ -37,12 +39,12 @@ sphinx = "3.1.2"
 sphinx-rtd-theme = "0.5.0"
 asv = "^0.4.2"
 
-
 [tool.poetry.scripts]
+betterproto = "betterproto:__main__.main"
 protoc-gen-python_betterproto = "betterproto.plugin:main"
 
 [tool.poetry.extras]
-compiler = ["black", "jinja2"]
+compiler = ["black", "jinja2", "typer", "rich"]
 
 [tool.poe.tasks]
 # Dev workflow tasks

src/betterproto/__main__.py

@@ -0,0 +1,4 @@
+from .plugin.cli import app as main
+
+if __name__ == "__main__":
+    main()

src/betterproto/_types.py

@@ -2,6 +2,7 @@
 
 if TYPE_CHECKING:
     from grpclib._typing import IProtoMessage
+
     from . import Message
 
 # Bound type variable to allow methods to return `self` of subclasses

src/betterproto/plugin/__init__.py

@@ -1 +1,50 @@
+import sys
+import traceback
+from pathlib import Path
+from types import TracebackType
+from typing import Type
+
+IMPORT_ERROR_MESSAGE = (
+    "Unable to import `{0.name}` from betterproto plugin! Please ensure that you've installed "
+    'betterproto as `pip install "betterproto[compiler]"` so that compiler dependencies are '
+    "included."
+)
+
+STDLIB_MODULES = getattr(
+    sys,
+    "builtin_module_names",
+    [
+        p.with_suffix("").name
+        for p in Path(traceback.__file__).parent.iterdir()
+        if p.suffix == ".py" or p.is_dir()
+    ],
+)
+
+
+def import_exception_hook(
+    type: Type[BaseException], value: ImportError, tb: TracebackType
+) -> None:
+    """Set an exception hook to automatically print:
+
+    "Unable to import `x` from betterproto plugin! Please ensure that you've installed
+    betterproto as `pip install "betterproto[compiler]"` so that compiler dependencies are
+    included."
+
+    if the module imported is not found and the exception is raised in this sub module
+    """
+    module = list(traceback.walk_tb(tb))[-1][0].f_globals.get("__name__", "__main__")
+    if (
+        not module.startswith(__name__)
+        or not isinstance(value, ImportError)
+        or value.name in STDLIB_MODULES
+        or value.name.startswith("betterproto")
+    ):
+        return sys.__excepthook__(type, value, tb)
+
+    print(f"\033[31m{IMPORT_ERROR_MESSAGE.format(value)}\033[0m", file=sys.stderr)
+    exit(1)
+
+
+sys.excepthook = import_exception_hook
+
 from .main import main

src/betterproto/plugin/__main__.py

@@ -1,4 +1,3 @@
 from .main import main
 
-
 main()

src/betterproto/plugin/cli/__init__.py

@@ -0,0 +1,18 @@
+import asyncio
+import platform
+
+try:
+    import grpc_tools.protoc
+except ImportError:
+    USE_PROTOC = True
+else:
+    USE_PROTOC = False
+
+VERBOSE = False
+from black import DEFAULT_LINE_LENGTH as DEFAULT_LINE_LENGTH  # noqa
+
+from .commands import app
+from .runner import compile_protobufs
+
+if platform.system() == "Windows":
+    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())

src/betterproto/plugin/cli/commands.py

@@ -0,0 +1,116 @@
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import rich
+import typer
+from rich.syntax import Syntax
+
+from ..models import monkey_patch_oneof_index
+from . import DEFAULT_LINE_LENGTH, USE_PROTOC, VERBOSE, utils
+from .errors import CLIError, ProtobufSyntaxError
+from .runner import compile_protobufs
+
+monkey_patch_oneof_index()
+app = typer.Typer()
+
+
+@app.callback(context_settings={"help_option_names": ["-h", "--help"]})
+def callback(ctx: typer.Context) -> None:
+    """The callback for all things betterproto"""
+    if ctx.invoked_subcommand is None:
+        rich.print(ctx.get_help())
+
+
+@app.command(context_settings={"help_option_names": ["-h", "--help"]})
+@utils.run_sync
+async def compile(
+    verbose: bool = typer.Option(
+        VERBOSE, "-v", "--verbose", help="Whether or not to be verbose"
+    ),
+    protoc: bool = typer.Option(
+        USE_PROTOC,
+        "-p",
+        "--protoc",
+        help="Whether or not to use protoc to compile the protobufs if this is false "
+        "it will attempt to use grpc instead",
+    ),
+    line_length: int = typer.Option(
+        DEFAULT_LINE_LENGTH,
+        "-l",
+        "--line-length",
+        help="The line length to format with",
+    ),
+    generate_services: bool = typer.Option(
+        True, help="Whether or not to generate servicer stubs"
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        help="The name of the output directory",
+        file_okay=False,
+        allow_dash=True,
+    ),
+    paths: List[Path] = typer.Argument(
+        ...,
+        help="The protobuf files to compile",
+        exists=True,
+        allow_dash=True,
+        readable=False,
+    ),
+) -> None:
+    """The recommended way to compile your protobuf files."""
+    files = utils.get_files(paths)
+
+    if not files:
+        return rich.print("[bold]No files found to compile")
+
+    for output_path, protos in files.items():
+        output = output or (Path(output_path.parent.name) / output_path.name).resolve()
+        output.mkdir(exist_ok=True, parents=True)
+
+        errors = await compile_protobufs(
+            *protos,
+            output=output,
+            verbose=verbose,
+            use_protoc=protoc,
+            generate_services=generate_services,
+            line_length=line_length,
+            from_cli=True,
+        )
+
+        for error in errors:
+            if isinstance(error, ProtobufSyntaxError):
+                rich.print(
+                    f"[red]File {str(error.file).strip()}:\n",
+                    Syntax(
+                        error.file.read_text(),
+                        "proto",
+                        line_numbers=True,
+                        line_range=(max(error.lineno - 5, 0), error.lineno),
+                    ),  # TODO switch to .from_path but it appears to be bugged and doesnt render properly
+                    f"{' ' * (error.offset + 3)}^\nSyntaxError: {error.msg}[red]",
+                    file=sys.stderr,
+                )
+            elif isinstance(error, Warning):
+                rich.print(f"Warning: {error}", file=sys.stderr)
+            elif isinstance(error, CLIError):
+                failed_files = "\n".join(f" - {file}" for file in protos)
+                rich.print(
+                    f"[red]{'Protoc' if protoc else 'GRPC'} failed to generate outputs for:\n\n"
+                    f"{failed_files}\n\nSee the output for the issue:\n{' '.join(error.args)}[red]",
+                    file=sys.stderr,
+                )
+
+        has_warnings = all(isinstance(e, Warning) for e in errors)
+        if not errors or has_warnings:
+            rich.print(
+                f"[bold green]Finished generating output for "
+                f"{len(protos)} file{'s' if len(protos) != 1 else ''}, "
+                f"output is in {output.as_posix()}"
+            )
+
+        if errors:
+            if not has_warnings:
+                exit(2)
+            exit(1)
+        exit(0)