protodial 1.0.0__py3-none-any.whl

protodial/__init__.py

@@ -0,0 +1,3 @@
+"""Python command-line client for arbitrary gRPC services."""
+
+__version__ = "1.0.0"

protodial/__main__.py

@@ -0,0 +1,5 @@
+"""Module entry point for ``python -m protodial``."""
+
+from .cli import main
+
+raise SystemExit(main())

protodial/_rich_details.py

@@ -0,0 +1,35 @@
+"""Identify standard ``google.rpc`` rich-status detail messages.
+
+This dependency-light module is intentionally outside ``rich_status`` so the
+diagnostic bootstrap path can import it even when protobuf is unavailable.
+"""
+
+from __future__ import annotations
+
+STANDARD_DETAIL_NAMES = frozenset(
+    {
+        "BadRequest",
+        "DebugInfo",
+        "ErrorInfo",
+        "Help",
+        "LocalizedMessage",
+        "PreconditionFailure",
+        "QuotaFailure",
+        "RequestInfo",
+        "ResourceInfo",
+        "RetryInfo",
+    }
+)
+
+
+def standard_detail_name(identity: object) -> str | None:
+    """Return a standard detail's short name from an exact Any identity."""
+
+    full_name = str(identity).rsplit("/", 1)[-1]
+    prefix = "google.rpc."
+    if not full_name.startswith(prefix):
+        return None
+    short_name = full_name.removeprefix(prefix)
+    if short_name not in STANDARD_DETAIL_NAMES:
+        return None
+    return short_name

protodial/argument_parser/__init__.py

@@ -0,0 +1,7 @@
+"""Focused command-line parsing implementation."""
+
+from .construction import build_parser
+from .parsing import parse_arguments
+from .target import parse_target
+
+__all__ = ["build_parser", "parse_arguments", "parse_target"]

protodial/argument_parser/construction.py

@@ -0,0 +1,406 @@
+"""Construction of the protodial command-line parser."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import __version__
+from ..commands.models import (
+    DEFAULT_CHUNK_SIZE,
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_INPUT_BUFFER,
+    DEFAULT_TIMEOUT,
+)
+from ..formats import MessageFormat
+from ..schema.paths import default_proto_paths
+
+_FORMATS = tuple(message_format.value for message_format in MessageFormat)
+EXAMPLES = """\
+Examples:
+  protodial [options...] grpc://HOST/SERVICE/METHOD
+  protodial [options...] --method SERVICE/METHOD TARGET
+  protodial list [options...] TARGET [SERVICE]
+  protodial describe [options...] TARGET SYMBOL
+  protodial describe [options...] grpc://HOST/SYMBOL
+  protodial describe [options...] grpc://HOST/SERVICE/METHOD
+
+Run `protodial list --help` or `protodial describe --help` for discovery
+options."""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the complete command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="protodial",
+        description=(
+            "Call and discover gRPC services using reflection or local schemas."
+        ),
+        epilog=EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    subparsers = parser.add_subparsers(
+        dest="command_name", metavar="COMMAND", required=True
+    )
+
+    list_parser = subparsers.add_parser(
+        "list", help="list services or methods", allow_abbrev=False
+    )
+    _add_shared_arguments(list_parser)
+    list_parser.add_argument(
+        "--show-reflection",
+        action="store_true",
+        help="include reflection services in list output",
+    )
+    list_parser.add_argument("target", help="gRPC target or grpc[s]:// URL")
+    list_parser.add_argument(
+        "service",
+        nargs="?",
+        help="service name (may instead be included in the URL path)",
+    )
+    list_parser.set_defaults(get_template=False)
+
+    describe = subparsers.add_parser(
+        "describe", help="describe a schema symbol", allow_abbrev=False
+    )
+    _add_shared_arguments(describe)
+    describe.add_argument(
+        "--template",
+        action="store_true",
+        dest="get_template",
+        help=(
+            "print sample ProtoJSON for a message or method request instead "
+            "of its declaration"
+        ),
+    )
+    describe.add_argument(
+        "--template-depth",
+        type=int,
+        default=argparse.SUPPRESS,
+        help="maximum template nesting depth (default: 8)",
+    )
+    describe.add_argument(
+        "target",
+        help="gRPC target or grpc[s]:// URL containing the symbol or method",
+    )
+    describe.add_argument(
+        "symbol",
+        nargs="?",
+        help="schema symbol (when it is not included in TARGET)",
+    )
+    describe.set_defaults(show_reflection=False)
+    return parser
+
+
+def build_invocation_parser() -> argparse.ArgumentParser:
+    """Build the parser for the implicit default invocation command."""
+    parser = argparse.ArgumentParser(
+        prog="protodial",
+        description=(
+            "Invoke a gRPC method, or use list/describe for schema discovery."
+        ),
+        epilog=EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    _add_shared_arguments(parser)
+    _add_invocation_arguments(parser)
+    _add_rpc_metadata_argument(parser)
+    _add_response_diagnostic_arguments(parser)
+    parser.add_argument(
+        "--method",
+        help="SERVICE/METHOD for a resolver or Unix-socket target",
+    )
+    parser.add_argument(
+        "target",
+        help="grpc[s]:// invocation URL or native gRPC channel target",
+    )
+    parser.set_defaults(
+        command_name="invoke", get_template=False, show_reflection=False
+    )
+    return parser
+
+
+def _add_shared_arguments(parser: argparse.ArgumentParser) -> None:
+    _add_schema_arguments(parser)
+    _add_transport_arguments(parser)
+    _add_connection_arguments(parser)
+    _add_metadata_arguments(parser)
+    _add_diagnostic_arguments(parser)
+
+
+def _add_schema_arguments(parser: argparse.ArgumentParser) -> None:
+    proto_paths = default_proto_paths()
+    parser.add_argument(
+        "--proto", action="append", default=[], help="local .proto (repeatable)"
+    )
+    parser.add_argument(
+        "--protoset",
+        action="append",
+        default=[],
+        help="FileDescriptorSet (repeatable)",
+    )
+    parser.add_argument(
+        "--protoset-out", help="atomically write the complete descriptor set"
+    )
+    parser.add_argument(
+        "--use-reflection",
+        action="store_true",
+        help="use reflection for missing local symbols",
+    )
+    parser.add_argument(
+        "--proto-path",
+        action="append",
+        default=list(proto_paths),
+        help=(
+            "proto import root "
+            f"(repeatable; defaults: {', '.join(proto_paths)})"
+        ),
+    )
+
+
+def _add_invocation_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-d",
+        "--data",
+        default=argparse.SUPPRESS,
+        help="literal input; @path reads a file; - or @- reads stdin",
+    )
+    parser.add_argument(
+        "--input-format",
+        choices=_FORMATS,
+        default=argparse.SUPPRESS,
+        help="request encoding (default: json)",
+    )
+    parser.add_argument(
+        "--output-format",
+        choices=_FORMATS,
+        default=argparse.SUPPRESS,
+        help="response encoding (default: json)",
+    )
+    parser.add_argument(
+        "--field",
+        action="append",
+        default=argparse.SUPPRESS,
+        metavar="NAME=VALUE",
+        help="set a field on each raw input message (repeatable)",
+    )
+    parser.add_argument(
+        "--field:file",
+        dest="field_file",
+        action="append",
+        default=argparse.SUPPRESS,
+        metavar="NAME=PATH",
+        help="read a file (- for stdin) into a bytes field and use raw input",
+    )
+    parser.add_argument(
+        "--input-field",
+        default=argparse.SUPPRESS,
+        help="bytes field for raw input",
+    )
+    parser.add_argument(
+        "--output-field",
+        default=argparse.SUPPRESS,
+        help="bytes field for raw output",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=argparse.SUPPRESS,
+        help=f"raw stream chunk size in bytes (default: {DEFAULT_CHUNK_SIZE})",
+    )
+    parser.add_argument(
+        "--allow-unknown-fields",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="ignore unknown ProtoJSON input fields",
+    )
+    parser.add_argument(
+        "--emit-defaults",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="include fields with default values in ProtoJSON output",
+    )
+    parser.add_argument(
+        "--max-input-buffer",
+        type=int,
+        default=argparse.SUPPRESS,
+        help=f"maximum buffered input bytes (default: {DEFAULT_INPUT_BUFFER})",
+    )
+    parser.add_argument(
+        "--interactive",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="unsupported; use --data - or --data @- for streaming stdin",
+    )
+    parser.add_argument(
+        "--wait-for-ready",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help=(
+            "let the RPC wait for readiness until --max-time; local schemas "
+            "skip the connection preflight"
+        ),
+    )
+
+
+def _add_transport_arguments(parser: argparse.ArgumentParser) -> None:
+    transport = parser.add_mutually_exclusive_group()
+    transport.add_argument(
+        "--plaintext", action="store_true", help="disable TLS"
+    )
+    transport.add_argument(
+        "-k",
+        "--insecure",
+        action="store_true",
+        help="disable TLS peer verification (unsafe)",
+    )
+    parser.add_argument(
+        "--cacert",
+        action="append",
+        default=[],
+        help="PEM CA bundle (repeatable)",
+    )
+    parser.add_argument("--cert", help="PEM client certificate")
+    parser.add_argument("--key", help="PEM client private key")
+    parser.add_argument(
+        "--key-password",
+        help="client private-key password (may be visible in shell history)",
+    )
+    parser.add_argument(
+        "--servername", help="TLS SNI and verified server identity"
+    )
+    parser.add_argument("--authority", help="HTTP/2 :authority value")
+
+
+def _add_connection_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--connect-timeout",
+        type=float,
+        default=DEFAULT_CONNECT_TIMEOUT,
+        help=(
+            "channel readiness timeout in seconds "
+            f"(default: {DEFAULT_CONNECT_TIMEOUT:g})"
+        ),
+    )
+    parser.add_argument(
+        "-m",
+        "--max-time",
+        dest="timeout",
+        metavar="SECONDS",
+        type=float,
+        default=DEFAULT_TIMEOUT,
+        help="maximum RPC time in seconds",
+    )
+    parser.add_argument(
+        "--max-recv-message-size",
+        type=int,
+        help="maximum response message bytes",
+    )
+    parser.add_argument(
+        "--max-send-message-size",
+        type=int,
+        help="maximum request message bytes",
+    )
+    parser.add_argument(
+        "--compression",
+        choices=("none", "gzip", "deflate"),
+        default="none",
+        help="gRPC message compression (default: none)",
+    )
+    parser.add_argument(
+        "--keepalive-time",
+        type=float,
+        help="HTTP/2 keepalive interval in seconds",
+    )
+    parser.add_argument(
+        "-A", "--user-agent", help="gRPC primary user-agent value"
+    )
+
+
+def _add_metadata_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "-H",
+        "--header",
+        action="append",
+        default=[],
+        help="shared metadata key:value",
+    )
+    parser.add_argument(
+        "--reflect-header",
+        action="append",
+        default=[],
+        help="reflection-only metadata",
+    )
+    parser.add_argument(
+        "--expand-headers", action="store_true", help="expand $NAME and ${NAME}"
+    )
+
+
+def _add_rpc_metadata_argument(parser: argparse.ArgumentParser) -> None:
+    """Add metadata which is meaningful only for method invocation."""
+    parser.add_argument(
+        "--rpc-header",
+        action="append",
+        default=[],
+        help="application RPC-only metadata",
+    )
+
+
+def _add_diagnostic_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--color",
+        choices=("auto", "always", "never"),
+        default=argparse.SUPPRESS,
+        help="diagnostic color policy (default: auto)",
+    )
+    parser.add_argument(
+        "--diagnostic-format",
+        choices=("human", "json"),
+        default=argparse.SUPPRESS,
+        help="stderr diagnostic encoding (default: human)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="increase stderr diagnostics",
+    )
+    parser.set_defaults(
+        show_headers=False,
+        show_trailers=False,
+        show_status=False,
+        format_error=False,
+    )
+
+
+def _add_response_diagnostic_arguments(
+    parser: argparse.ArgumentParser,
+) -> None:
+    parser.add_argument(
+        "-i",
+        "--include",
+        dest="show_headers",
+        action="store_true",
+        help="include response metadata on stderr",
+    )
+    parser.add_argument(
+        "--show-trailers", action="store_true", help="show response trailers"
+    )
+    parser.add_argument(
+        "--show-status",
+        action="store_true",
+        help="show final status and counts",
+    )
+    parser.add_argument(
+        "--format-error",
+        action="store_true",
+        help="decode structured gRPC errors",
+    )

protodial/argument_parser/parsing.py

@@ -0,0 +1,115 @@
+"""Top-level command parsing and configuration assembly."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+
+from ..commands.models import (
+    Command,
+    ConnectionOptions,
+    DiagnosticOptions,
+    InvokeOptions,
+    MetadataOptions,
+    ParsedTarget,
+    SchemaOptions,
+    TlsOptions,
+)
+from ..commands.operations import Operation
+from .construction import build_invocation_parser, build_parser
+from .resolution import resolve_command, resolve_transport_mode
+from .validation import (
+    validate_common_options,
+    validate_invocation_options,
+    validate_operation_options,
+)
+
+
+def _build_command(
+    namespace: argparse.Namespace,
+    target: ParsedTarget,
+    operation: Operation,
+    invoke_options: InvokeOptions | None,
+    transport_mode: str,
+) -> Command:
+    verbosity = namespace.verbose
+    return Command(
+        target=target,
+        operation=operation,
+        schema=SchemaOptions(
+            proto=tuple(namespace.proto),
+            proto_path=tuple(namespace.proto_path),
+            protoset=tuple(namespace.protoset),
+            protoset_out=namespace.protoset_out,
+            use_reflection=namespace.use_reflection,
+        ),
+        transport=TlsOptions(
+            mode=transport_mode,
+            ca_paths=tuple(namespace.cacert),
+            cert=namespace.cert,
+            key=namespace.key,
+            key_password=namespace.key_password,
+            server_name=namespace.servername,
+            authority=namespace.authority,
+        ),
+        connection=ConnectionOptions(
+            connect_timeout=namespace.connect_timeout,
+            max_recv_message_size=namespace.max_recv_message_size,
+            max_send_message_size=namespace.max_send_message_size,
+            compression=namespace.compression,
+            keepalive_time=namespace.keepalive_time,
+            user_agent=namespace.user_agent,
+        ),
+        metadata=MetadataOptions(
+            header=tuple(namespace.header),
+            reflect_header=tuple(namespace.reflect_header),
+            rpc_header=tuple(getattr(namespace, "rpc_header", ())),
+            expand_headers=namespace.expand_headers,
+        ),
+        diagnostics=DiagnosticOptions(
+            show_headers=verbosity > 0 or namespace.show_headers,
+            show_trailers=verbosity > 0 or namespace.show_trailers,
+            show_status=verbosity > 0 or namespace.show_status,
+            verbosity=verbosity,
+            format_error=namespace.format_error or verbosity > 0,
+            diagnostic_format=namespace.diagnostic_format,
+            color=namespace.color,
+        ),
+        timeout=namespace.timeout,
+        invoke_options=invoke_options,
+        get_template=namespace.get_template,
+        template_depth=getattr(namespace, "template_depth", 8),
+        show_reflection=namespace.show_reflection,
+    )
+
+
+def parse_arguments(argv: Sequence[str] | None = None) -> Command:
+    """Parse command-line arguments into validated command configuration."""
+    parser = build_parser()
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] not in {"list", "describe"}:
+        # Invocation is the default mode. Discovery commands must still occupy
+        # argv[0], so `--option list ...` is never reinterpreted as discovery.
+        parser = build_invocation_parser()
+    namespace = parser.parse_args(arguments)
+    if not hasattr(namespace, "diagnostic_format"):
+        diagnostic_format = os.environ.get(
+            "PROTODIAL_DIAGNOSTIC_FORMAT", "human"
+        )
+        if diagnostic_format not in {"human", "json"}:
+            parser.error(
+                "PROTODIAL_DIAGNOSTIC_FORMAT must be one of: human, json"
+            )
+        namespace.diagnostic_format = diagnostic_format
+    if not hasattr(namespace, "color"):
+        namespace.color = "auto"
+    target, operation = resolve_command(parser, namespace)
+    invoke_options = validate_invocation_options(parser, namespace, operation)
+    validate_common_options(parser, namespace)
+    transport_mode = resolve_transport_mode(parser, namespace, target)
+    validate_operation_options(parser, namespace, operation)
+    return _build_command(
+        namespace, target, operation, invoke_options, transport_mode
+    )