Fix name collisions between service-defined shapes and framework types

[Alan4506]

Problem

When generating a Python client for services like Q Business, the codegen produces invalid Python code due to two categories of name collisions:

1. schemas.py — import collision

The Q Business model defines com.amazonaws.qbusiness#Blob. The codegen generates a local BLOB = Schema(...) in schemas.py. A member elsewhere targets smithy.api#Blob, causing from smithy_core.prelude import BLOB to be added in schemas.py. The local definition shadows the import.

2. models.py — import collision

The Q Business model defines com.amazonaws.qbusiness#Document. The codegen generates class Document: in models.py. The model also defines document type shapes (e.g., ActionPayloadFieldValue), causing from smithy_core.documents import Document to be added in models.py. The local class definition shadows the import.

3. models.py — union member variant name collision

The Q Business model defines:

"com.amazonaws.qbusiness#Principal": {
    "type": "union",
    "members": {
        "user": {
            "target": "com.amazonaws.qbusiness#PrincipalUser"
        }
    }
}

The codegen synthesizes variant class name Principal + capitalize("user") = PrincipalUser, which collides with the target structure PrincipalUser that is also generated as a separate class in the same file.

Additionally, the framework defines AuthOption in both smithy_core.auth and smithy_core.interfaces.auth. When both are imported into the same file (e.g., auth.py), one shadows the other. This was previously handled with manual aliases (e.g., addImport("smithy_core.interfaces.auth", "AuthOption", "AuthOptionProtocol")), along with similar manual aliases for EndpointResolver and HTTPResponse. These worked but were ad-hoc — each case required a hardcoded alias in the generator code. Our change replaces all manual aliases with a unified automatic collision detection system.

Description of Changes

Import collisions — deferred collision detection in PythonWriter

Inspired by smithy-java's DeferredSymbolWriter pattern:

• Created RuntimeTypes.java and AwsRuntimeTypes.java with pre-defined Symbol constants for all framework types used across generators. This replaces hardcoded writer.addImport("smithy_core.X", "Name") + string literal "Name" patterns with $T using RuntimeTypes symbols, making all framework type references visible to the collision detection system.

• Modified PythonWriter to track a symbol table (all symbols referenced via $T, keyed by simple name) and a locally-defined names set (class names and top-level variables registered by generators via addLocallyDefinedSymbol()). The $T formatter now returns a placeholder token («namespace.Name») instead of the final name. At toString() time, resolveCollisions() compares the two sets and:

  • If an imported name collides with a locally-defined name → aliases the import as _Name
  • If two imports share the same simple name → aliases each with a module-based name (e.g., _smithy_core_auth_AuthOption and _smithy_core_interfaces_auth_AuthOption)
  • Import statements are generated after collision resolution so aliases take effect

• Added aliasImport() to ImportDeclarations to retroactively rewrite an import's alias at toString() time.

• All generators that define classes or top-level names now call addLocallyDefinedSymbol().

Union member variant collisions — name check in PythonSymbolProvider

• Added allShapeNames set to PythonSymbolProvider, populated at construction time with the PascalCase names of all shapes that generate classes (structure, union, enum, intEnum).

• In memberShape(), after synthesizing the variant name (UnionName + capitalize(MemberName)), checks if it collides with any shape name. If so, uses UnionName_MemberName (e.g., Principal_User) instead. Smithy shape names cannot contain underscores, so this format is guaranteed collision-free.

• Same check in unionShape() for the Unknown variant (UnionName + "Unknown" → UnionName_Unknown if collision detected).

Testing

We successfully generated Q Business code with no ruff errors and no pyright errors. We inspected the generated code:

Import collisions resolved — models.py:

from smithy_core.documents import Document as _Document, TypeRegistry
# ...
class Document:  # service-defined class keeps its name
    """A document in an Amazon Q Business application."""
# ...
value: _Document  # framework Document uses alias

Import collisions resolved — _private/schemas.py:

from smithy_core.prelude import BLOB as _BLOB, BOOLEAN, UNIT
# ...
BLOB = Schema(id=ShapeID("com.amazonaws.qbusiness#Blob"), ...)  # local definition keeps its name
members={"blob": {"target": _BLOB}, ...}  # prelude BLOB uses alias

Import-vs-import collision resolved — auth.py:

from smithy_core.auth import AuthOption as _smithy_core_auth_AuthOption, AuthParams
from smithy_core.interfaces.auth import AuthOption as _smithy_core_interfaces_auth_AuthOption

Import-vs-import collision resolved — tests/test_protocol.py:

from smithy_http.aio import HTTPResponse as _smithy_http_aio_HTTPResponse
from smithy_http.aio.interfaces import HTTPRequest, HTTPResponse as _smithy_http_aio_interfaces_HTTPResponse

Union member variant collision resolved — models.py:

class PrincipalUser:    # service-defined structure, unchanged
class PrincipalGroup:   # service-defined structure, unchanged
class Principal_User:   # union variant, disambiguated with "_"
class Principal_Group:  # union variant, disambiguated with "_"

We also locally tested that all modules import successfully, and integration tests pass.

We also regenerated all three existing clients (Bedrock Runtime, Sagemaker Runtime, Transcribe Streaming). All build successfully and tests pass.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ubaskota]

I noticed REST_JSON_CLIENT_PROTOCOL and STATIC_CREDENTIALS_RESOLVER are defined in both RuntimeTypes.java and AwsRuntimeTypes.java. Was the duplication intentional? Do we need them in both files?

[Alan4506]

Good catch! The duplication was unintentional. These two symbols are only used by generators in the core module (RestJsonProtocolGenerator and HttpProtocolTestGenerator), which should not depend on the AWS module. I've removed them from AwsRuntimeTypes.java and kept them only in RuntimeTypes.java.

[jonathan343]

Thanks @Alan4506!

I left some comments on potential gaps we should look into. Can you look into these and address if appropriate? It would also be ideal to add some related tests to prevent regressions

[jonathan343]

This collision handling also needs to update stdlib imports when it rewrites symbol references.

Example: if a Smithy model defines a structure named Decimal and another shape uses bigDecimal, the generated Python can end up like this:

from decimal import Decimal

class Decimal:
    ...

@dataclass
class Foo:
    value: _Decimal

The body was rewritten to use _Decimal, but the import still exposes Decimal, so importing the module fails with NameError: name '_Decimal' is not defined.

Could we either include stdlibImports in the alias rewrite path or avoid aliasing stdlib symbols here? If you considered this and there is an issue with it, let me know

[jonathan343]

This early return seems too broad. A symbol with a definition file may still be imported into a different generated file, so skipping it here can hide real name collisions from the import resolver.

Example: config.py may need both a runtime resolver and a generated model with the same name:

from smithy_aws_core.endpoints import StandardRegionalEndpointsResolver
from .models import StandardRegionalEndpointsResolver

class Config:
    def __init__(self):
        self.endpoint_resolver = StandardRegionalEndpointsResolver(
            endpoint_prefix="..."
        )

The .models import shadows the runtime resolver, so this calls the generated model class with resolver arguments. The expected output would alias one of them, for example:

from smithy_aws_core.endpoints import StandardRegionalEndpointsResolver as _RegionalResolver
from .models import StandardRegionalEndpointsResolver

Could we only skip symbols that are actually defined in the current writer, while still registering generated symbols that are imported from other generated files?