smithy-python 0.1.0__tar.gz

smithy_python-0.1.0/.changes/0.1.0.json

@@ -0,0 +1,16 @@
+{
+  "changes": [
+    {
+      "type": "feature",
+      "description": "Added the experimental smithy-python package and CLI scaffold."
+    },
+    {
+      "type": "feature",
+      "description": "Added service and data-shape selection for the native Python generator, including `--service` for `client` and `types` commands, service closure filtering, and standalone types name conflict diagnostics."
+    },
+    {
+      "type": "feature",
+      "description": "Added a Smithy JSON AST model loader with an embedded prelude, mixin flattening, and apply support."
+    }
+  ]
+}

smithy_python-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Eclipse
+.classpath
+.project
+.settings/
+
+# Intellij
+.idea/
+*.iml
+*.iws
+
+# VS Code
+.vscode/
+
+# Mac
+.DS_Store
+
+# Maven
+target/
+**/dependency-reduced-pom.xml
+
+# Gradle
+**/.gradle
+build/
+*/out/
+**/*/out/
+
+# Python
+__pycache__
+*.swp
+.mypy_cache
+.coverage
+coverage.xml
+htmlcov
+*.egg-info
+dist
+.venv

smithy_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## v0.1.0
+
+### Features
+* Added the experimental smithy-python package and CLI scaffold.
+* Added service and data-shape selection for the native Python generator, including `--service` for `client` and `types` commands, service closure filtering, and standalone types name conflict diagnostics.
+* Added a Smithy JSON AST model loader with an embedded prelude, mixin flattening, and apply support.

smithy_python-0.1.0/NOTICE

@@ -0,0 +1 @@
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

smithy_python-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: smithy-python
+Version: 0.1.0
+Summary: A Smithy code generator for Python clients and types.
+Project-URL: Changelog, https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-python/CHANGELOG.md
+Project-URL: Code, https://github.com/smithy-lang/smithy-python/tree/develop/packages/smithy-python/
+Project-URL: Issue tracker, https://github.com/smithy-lang/smithy-python/issues
+Author: Amazon Web Services
+License: Apache License 2.0
+License-File: NOTICE
+Keywords: codegen,sdk,smithy
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# smithy-python
+
+> [!WARNING]
+> This package is an experimental scaffold. It does not generate code yet. The
+> Java generator in the repository's `codegen` directory remains authoritative.
+
+`smithy-python` will provide Python-native code generation for Smithy models.
+The initial command-line interface exposes the planned client and types generation
+commands so that their top-level shape can be developed independently from the
+generator implementation.
+
+```console
+smithy-python generate client [OPTIONS]
+smithy-python generate types [OPTIONS]
+```
+
+After validating their invocation options, both generation commands currently exit
+with an error explaining that generation has not been implemented. The package is
+included in workspace builds to validate its packaging and entry points.

smithy_python-0.1.0/README.md

@@ -0,0 +1,19 @@
+# smithy-python
+
+> [!WARNING]
+> This package is an experimental scaffold. It does not generate code yet. The
+> Java generator in the repository's `codegen` directory remains authoritative.
+
+`smithy-python` will provide Python-native code generation for Smithy models.
+The initial command-line interface exposes the planned client and types generation
+commands so that their top-level shape can be developed independently from the
+generator implementation.
+
+```console
+smithy-python generate client [OPTIONS]
+smithy-python generate types [OPTIONS]
+```
+
+After validating their invocation options, both generation commands currently exit
+with an error explaining that generation has not been implemented. The package is
+included in workspace builds to validate its packaging and entry points.

smithy_python-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "smithy-python"
+dynamic = ["version"]
+requires-python = ">=3.12"
+authors = [
+  {name = "Amazon Web Services"},
+]
+description = "A Smithy code generator for Python clients and types."
+readme = "README.md"
+license = {text = "Apache License 2.0"}
+keywords = ["smithy", "codegen", "sdk"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Free Threading :: 2 - Beta",
+  "Topic :: Software Development :: Code Generators",
+]
+dependencies = []
+
+[project.scripts]
+smithy-python = "smithy_python.cli:main"
+
+[project.urls]
+"Changelog" = "https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-python/CHANGELOG.md"
+"Code" = "https://github.com/smithy-lang/smithy-python/tree/develop/packages/smithy-python/"
+"Issue tracker" = "https://github.com/smithy-lang/smithy-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/smithy_python/__init__.py"
+
+[tool.hatch.build]
+exclude = [
+  "tests",
+]
+
+[tool.ruff]
+src = ["src"]

smithy_python-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]