smithy-python 0.1.0__py3-none-any.whl

smithy_python/__init__.py

@@ -0,0 +1,5 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""A Smithy code generator for Python clients and types."""
+
+__version__ = "0.1.0"

smithy_python/__main__.py

@@ -0,0 +1,7 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

smithy_python/cli.py

@@ -0,0 +1,180 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Command-line interface for the Smithy Python code generator."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Final
+
+from . import __version__
+from .environment import PluginEnvironment
+from .exceptions import CodegenError, InvalidInvocationError
+from .model import load_model
+from .selection import select_shapes
+
+_GENERATION_NOT_IMPLEMENTED: Final = (
+    "smithy-python: error: {artifact} generation is not implemented yet\n"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _Invocation:
+    artifact: str
+    model_source: bytes
+    output_dir: Path
+    environment: PluginEnvironment
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    environ: Mapping[str, str] | None = None,
+    stdin: BinaryIO | None = None,
+) -> int:
+    """Run the CLI with the provided process inputs and return its exit code."""
+    parser = _create_parser()
+
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as error:
+        return error.code if isinstance(error.code, int) else 1
+
+    try:
+        invocation = _resolve_invocation(args, environ=environ, stdin=stdin)
+    except InvalidInvocationError as error:
+        sys.stderr.write(f"smithy-python: error: {error}\n")
+        return 2
+    except (CodegenError, OSError) as error:
+        sys.stderr.write(f"smithy-python: error: {error}\n")
+        return 1
+
+    try:
+        model = load_model(invocation.model_source)
+        selection = select_shapes(
+            model,
+            service_id=args.service,
+            require_service=invocation.artifact == "client",
+        )
+    except InvalidInvocationError as error:
+        sys.stderr.write(f"smithy-python: error: {error}\n")
+        return 2
+    except CodegenError as error:
+        sys.stderr.write(f"smithy-python: error: {error}\n")
+        return 1
+
+    if selection.excluded_count and selection.service is not None:
+        sys.stderr.write(
+            f"smithy-python: excluded {selection.excluded_count} eligible data shape(s) "
+            f"outside the closure of service {selection.service.id}\n"
+        )
+    sys.stderr.write(_GENERATION_NOT_IMPLEMENTED.format(artifact=args.artifact))
+    return 1
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="smithy-python",
+        description="Generate Python source from Smithy models.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    commands = parser.add_subparsers(required=True)
+    generate = commands.add_parser("generate", help="Generate Python source")
+    artifacts = generate.add_subparsers(dest="artifact", required=True)
+    common = _common_artifact_options()
+    for name, help_text in (
+        ("client", "Generate a client package"),
+        ("types", "Generate a standalone types package"),
+    ):
+        artifacts.add_parser(name, help=help_text, parents=[common])
+
+    return parser
+
+
+def _common_artifact_options() -> argparse.ArgumentParser:
+    """Build a parent parser with the options shared by every artifact."""
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument(
+        "--service",
+        metavar="SHAPE_ID",
+        help="Absolute service shape ID; defaults to the sole non-mixin service.",
+    )
+    parser.add_argument(
+        "--model",
+        type=Path,
+        help=(
+            "The Smithy JSON AST model file to use for code generation. "
+            "If not set, the model is read from standard input."
+        ),
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help=(
+            "Output directory for generated files. Defaults to the Smithy run "
+            "plugin's output directory (SMITHY_PLUGIN_DIR) when invoked by Smithy."
+        ),
+    )
+    return parser
+
+
+def _resolve_invocation(
+    args: argparse.Namespace,
+    *,
+    environ: Mapping[str, str] | None,
+    stdin: BinaryIO | None,
+) -> _Invocation:
+    # PluginEnvironment falls back to os.environ, so the defaulting lives there.
+    environment = PluginEnvironment.from_environ(environ)
+    model_path: Path | None = args.model
+    output_path: Path | None = args.output
+
+    if (plugin_dir := environment.plugin_dir) is not None:
+        if model_path is not None:
+            raise InvalidInvocationError(
+                "--model cannot be used with the Smithy run plugin"
+            )
+        if output_path is not None:
+            raise InvalidInvocationError(
+                "--output cannot be used with the Smithy run plugin"
+            )
+        output_dir = plugin_dir
+    else:
+        if output_path is None:
+            raise InvalidInvocationError("Direct invocation requires --output")
+        output_dir = output_path
+
+    if model_path is not None:
+        # A model that cannot be read is an I/O failure like any other, whether
+        # the path is missing, a directory, or unreadable.
+        try:
+            model_source = model_path.read_bytes()
+        except OSError as error:
+            raise OSError(
+                f"Cannot read model {model_path}: {error.strerror or error}"
+            ) from error
+    else:
+        model_stream = sys.stdin.buffer if stdin is None else stdin
+        if environment.plugin_dir is None and model_stream.isatty():
+            raise InvalidInvocationError(
+                "Direct invocation requires --model or a model piped to standard input"
+            )
+        model_source = model_stream.read()
+    if not model_source:
+        raise InvalidInvocationError("Expected a Smithy JSON AST model")
+
+    return _Invocation(
+        artifact=args.artifact,
+        model_source=model_source,
+        output_dir=output_dir,
+        environment=environment,
+    )

smithy_python/environment.py

@@ -0,0 +1,40 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Smithy build environment provided to the code generator."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Self
+
+
+@dataclass(frozen=True, slots=True)
+class PluginEnvironment:
+    """Environment values supplied by Smithy's process-based run plugin."""
+
+    root_dir: Path | None = None
+    plugin_dir: Path | None = None
+    projection_name: str | None = None
+    artifact_name: str | None = None
+    includes_prelude: bool = False
+
+    @classmethod
+    def from_environ(cls, environ: Mapping[str, str] | None = None) -> Self:
+        """Load the Smithy run plugin environment from a mapping."""
+
+        source = os.environ if environ is None else environ
+
+        def path(name: str) -> Path | None:
+            return Path(value) if (value := source.get(name)) else None
+
+        return cls(
+            root_dir=path("SMITHY_ROOT_DIR"),
+            plugin_dir=path("SMITHY_PLUGIN_DIR"),
+            projection_name=source.get("SMITHY_PROJECTION_NAME"),
+            artifact_name=source.get("SMITHY_ARTIFACT_NAME"),
+            includes_prelude=source.get("SMITHY_INCLUDES_PRELUDE", "false").lower()
+            == "true",
+        )

smithy_python/exceptions.py

@@ -0,0 +1,27 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Exceptions raised by Smithy Python code generation."""
+
+
+class SmithyPythonError(Exception):
+    """Base exception for errors raised by the Smithy Python generator."""
+
+
+class CodegenError(SmithyPythonError):
+    """Raised when code generation fails."""
+
+
+class InvalidInvocationError(SmithyPythonError):
+    """Raised when command-line inputs do not form a valid invocation."""
+
+
+class ModelError(CodegenError):
+    """Raised when a Smithy model cannot be loaded or navigated."""
+
+
+class InvalidShapeIdError(ModelError, ValueError):
+    """Raised when a string is not a valid Smithy shape ID."""
+
+
+class ShapeNotFoundError(ModelError, LookupError):
+    """Raised when a shape ID does not resolve to a shape in the model."""

smithy_python/model/__init__.py

@@ -0,0 +1,56 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""The Smithy semantic model used by the Python code generator.
+
+Use :func:`load_model` to parse a Smithy JSON AST into a :class:`Model`. The
+loaded model is mixin-flattened, has ``apply`` entries merged, includes the
+embedded Smithy prelude, and preserves the order of everything in the input.
+"""
+
+from ..exceptions import InvalidShapeIdError, ModelError, ShapeNotFoundError
+from ._loader import load_model
+from ._model import Model
+from ._shape_id import ShapeId
+from ._shapes import (
+    EnumShape,
+    IntEnumShape,
+    JsonValue,
+    ListShape,
+    MapShape,
+    MemberShape,
+    Node,
+    OperationShape,
+    ResourceShape,
+    ServiceShape,
+    Shape,
+    ShapeType,
+    SimpleShape,
+    StructureShape,
+    UnionShape,
+    to_json,
+)
+
+__all__ = [
+    "EnumShape",
+    "IntEnumShape",
+    "InvalidShapeIdError",
+    "JsonValue",
+    "ListShape",
+    "MapShape",
+    "MemberShape",
+    "Model",
+    "ModelError",
+    "Node",
+    "OperationShape",
+    "ResourceShape",
+    "ServiceShape",
+    "Shape",
+    "ShapeId",
+    "ShapeNotFoundError",
+    "ShapeType",
+    "SimpleShape",
+    "StructureShape",
+    "UnionShape",
+    "load_model",
+    "to_json",
+]