User agent

CONTRIBUTING.md

@@ -32,7 +32,7 @@ To send us a pull request, please:
 1. Fork the repository.
 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
 3. Ensure local tests pass (`make test-py` and `make test-protocols`).
-4. Run `make lint-py` if you've changed any python sources.
+4. Run `make lint-py` and `make check-py` if you've changed any python sources.
 4. Commit to your fork using clear commit messages.
 5. Send us a pull request, answering any default questions in the pull request interface.
 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

codegen/aws/core/src/main/java/software/amazon/smithy/python/aws/codegen/AwsPythonDependency.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.python.aws.codegen;
+
+import software.amazon.smithy.python.codegen.PythonDependency;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * AWS Dependencies used in the smithy python generator.
+ */
+@SmithyUnstableApi
+public class AwsPythonDependency {
+    /**
+     * The core aws smithy runtime python package.
+     *
+     * <p>While in development this will use the develop branch.
+     */
+    public static final PythonDependency SMITHY_AWS_CORE = new PythonDependency(
+            "smithy_aws_core",
+            // You'll need to locally install this before we publish
+            "==0.0.1",
+            PythonDependency.Type.DEPENDENCY,
+            false);
+}

codegen/aws/core/src/main/java/software/amazon/smithy/python/aws/codegen/AwsUserAgentIntegration.java

@@ -0,0 +1,114 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.python.aws.codegen;
+
+import java.util.List;
+import software.amazon.smithy.aws.traits.ServiceTrait;
+import software.amazon.smithy.codegen.core.Symbol;
+import software.amazon.smithy.codegen.core.SymbolReference;
+import software.amazon.smithy.python.codegen.CodegenUtils;
+import software.amazon.smithy.python.codegen.ConfigProperty;
+import software.amazon.smithy.python.codegen.GenerationContext;
+import software.amazon.smithy.python.codegen.integrations.PythonIntegration;
+import software.amazon.smithy.python.codegen.integrations.RuntimeClientPlugin;
+import software.amazon.smithy.utils.SmithyInternalApi;
+
+/**
+ * Adds a runtime plugin to set user agent.
+ */
+@SmithyInternalApi
+public class AwsUserAgentIntegration implements PythonIntegration {
+
+    public static final String USER_AGENT_PLUGIN = """
+            def aws_user_agent_plugin(config: $1T):
+                config.interceptors.append(
+                    $2T(
+                        ua_suffix=config.user_agent_extra,
+                        ua_app_id=config.sdk_ua_app_id,
+                        sdk_version=$3T,
+                        service_id='$4L'
+                    )
+                )
+            """;
+
+    @Override
+    public List<RuntimeClientPlugin> getClientPlugins(GenerationContext context) {
+        if (context.applicationProtocol().isHttpProtocol()) {
+            final ConfigProperty userAgentExtra = ConfigProperty.builder()
+                    .name("user_agent_extra")
+                    .documentation("Additional suffix to be added to the User-Agent header.")
+                    .type(Symbol.builder().name("str").build())
+                    .nullable(true)
+                    .build();
+
+            final ConfigProperty uaAppId = ConfigProperty.builder()
+                    .name("sdk_ua_app_id")
+                    .documentation(
+                            "A unique and opaque application ID that is appended to the User-Agent header.")
+                    .type(Symbol.builder().name("str").build())
+                    .nullable(true)
+                    .build();
+
+            final String user_agent_plugin_file = "user_agent";
+
+            final String moduleName = context.settings().moduleName();
+            final SymbolReference userAgentPlugin = SymbolReference.builder()
+                    .symbol(Symbol.builder()
+                            .namespace(String.format("%s.%s",
+                                    moduleName,
+                                    user_agent_plugin_file.replace('/', '.')), ".")
+                            .definitionFile(String
+                                    .format("./%s/%s.py", moduleName, user_agent_plugin_file))
+                            .name("aws_user_agent_plugin")
+                            .build())
+                    .build();
+            final SymbolReference userAgentInterceptor = SymbolReference.builder()
+                    .symbol(Symbol.builder()
+                            .namespace("smithy_aws_core.interceptors.user_agent", ".")
+                            .name("UserAgentInterceptor")
+                            .build())
+                    .build();
+            final SymbolReference versionSymbol = SymbolReference.builder()
+                    .symbol(Symbol.builder()
+                            .namespace(moduleName, ".")
+                            .name("__version__")
+                            .build())
+                    .build();
+
+            final String serviceId = context.settings()
+                    .service(context.model())
+                    .getTrait(ServiceTrait.class)
+                    .map(ServiceTrait::getSdkId)
+                    .orElse(context.settings().service().getName())
+                    .replace(' ', '_');
+
+            return List.of(
+                    RuntimeClientPlugin.builder()
+                            .addConfigProperty(userAgentExtra)
+                            .addConfigProperty(uaAppId)
+                            .pythonPlugin(userAgentPlugin)
+                            .writeAdditionalFiles((c) -> {
+                                String filename = "%s/%s.py".formatted(moduleName, user_agent_plugin_file);
+                                c.writerDelegator()
+                                        .useFileWriter(
+                                                filename,
+                                                moduleName + ".",
+                                                writer -> {
+                                                    writer.write(USER_AGENT_PLUGIN,
+                                                            CodegenUtils.getConfigSymbol(c.settings()),
+                                                            userAgentInterceptor,
+                                                            versionSymbol,
+                                                            serviceId);
+
+                                                });
+                                return List.of(filename);
+                            })
+                            .build());
+        } else {
+            return List.of();
+        }
+    }
+
+}

codegen/aws/core/src/main/resources/META-INF/services/software.amazon.smithy.python.codegen.integrations.PythonIntegration

@@ -5,3 +5,4 @@
 
 software.amazon.smithy.python.aws.codegen.AwsAuthIntegration
 software.amazon.smithy.python.aws.codegen.AwsProtocolsIntegration
+software.amazon.smithy.python.aws.codegen.AwsUserAgentIntegration

codegen/core/src/main/java/software/amazon/smithy/python/codegen/ClientGenerator.java

@@ -76,7 +76,7 @@ private void generateService(PythonWriter writer) {
             var defaultPlugins = new LinkedHashSet<SymbolReference>();
 
             for (PythonIntegration integration : context.integrations()) {
-                for (RuntimeClientPlugin runtimeClientPlugin : integration.getClientPlugins()) {
+                for (RuntimeClientPlugin runtimeClientPlugin : integration.getClientPlugins(context)) {
                     if (runtimeClientPlugin.matchesService(context.model(), service)) {
                         runtimeClientPlugin.getPythonPlugin().ifPresent(defaultPlugins::add);
                     }
@@ -678,7 +678,7 @@ private boolean hasEventStream() {
     private void initializeHttpAuthParameters(PythonWriter writer) {
         var derived = new LinkedHashSet<DerivedProperty>();
         for (PythonIntegration integration : context.integrations()) {
-            for (RuntimeClientPlugin plugin : integration.getClientPlugins()) {
+            for (RuntimeClientPlugin plugin : integration.getClientPlugins(context)) {
                 if (plugin.matchesService(context.model(), service)
                         && plugin.getAuthScheme().isPresent()
                         && plugin.getAuthScheme().get().getApplicationProtocol().isHttpProtocol()) {
@@ -767,7 +767,7 @@ private void writeSharedOperationInit(PythonWriter writer, OperationShape operat
 
         var defaultPlugins = new LinkedHashSet<SymbolReference>();
         for (PythonIntegration integration : context.integrations()) {
-            for (RuntimeClientPlugin runtimeClientPlugin : integration.getClientPlugins()) {
+            for (RuntimeClientPlugin runtimeClientPlugin : integration.getClientPlugins(context)) {
                 if (runtimeClientPlugin.matchesOperation(context.model(), service, operation)) {
                     runtimeClientPlugin.getPythonPlugin().ifPresent(defaultPlugins::add);
                 }

codegen/core/src/main/java/software/amazon/smithy/python/codegen/DirectedPythonCodegen.java

@@ -50,6 +50,7 @@
 import software.amazon.smithy.python.codegen.generators.StructureGenerator;
 import software.amazon.smithy.python.codegen.generators.UnionGenerator;
 import software.amazon.smithy.python.codegen.integrations.PythonIntegration;
+import software.amazon.smithy.python.codegen.integrations.RuntimeClientPlugin;
 import software.amazon.smithy.python.codegen.writer.PythonDelegator;
 import software.amazon.smithy.python.codegen.writer.PythonWriter;
 import software.amazon.smithy.utils.SmithyUnstableApi;
@@ -273,9 +274,39 @@ public void generateIntEnumShape(GenerateIntEnumDirective<GenerationContext, Pyt
 
     @Override
     public void customizeBeforeIntegrations(CustomizeDirective<GenerationContext, PythonSettings> directive) {
+        generateServiceModuleInit(directive);
+        generatePluginFiles(directive);
         generateInits(directive);
     }
 
+    /**
+     * Writes out all extra files required by runtime plugins.
+     */
+    private void generatePluginFiles(CustomizeDirective<GenerationContext, PythonSettings> directive) {
+        GenerationContext context = directive.context();
+        for (PythonIntegration integration : context.integrations()) {
+            for (RuntimeClientPlugin runtimeClientPlugin : integration.getClientPlugins(context)) {
+                if (runtimeClientPlugin.matchesService(context.model(), directive.service())) {
+                    runtimeClientPlugin.writeAdditionalFiles(context);
+                }
+            }
+        }
+    }
+
+    /**
+     * Creates top level __init__.py file.
+     */
+    private void generateServiceModuleInit(CustomizeDirective<GenerationContext, PythonSettings> directive) {
+        directive.context()
+                .writerDelegator()
+                .useFileWriter(
+                        "%s/__init__.py".formatted(directive.context().settings().moduleName()),
+                        writer -> {
+                            writer
+                                    .write("__version__: str = '$L'", directive.context().settings().moduleVersion());
+                        });
+    }
+
     /**
      * Creates __init__.py files where not already present.
      */

codegen/core/src/main/java/software/amazon/smithy/python/codegen/HttpAuthGenerator.java

@@ -43,7 +43,7 @@ public void run() {
         var properties = new ArrayList<DerivedProperty>();
         var service = context.settings().service(context.model());
         for (PythonIntegration integration : context.integrations()) {
-            for (RuntimeClientPlugin plugin : integration.getClientPlugins()) {
+            for (RuntimeClientPlugin plugin : integration.getClientPlugins(context)) {
                 if (plugin.matchesService(context.model(), service)
                         && plugin.getAuthScheme().isPresent()
                         && plugin.getAuthScheme().get().getApplicationProtocol().isHttpProtocol()) {

codegen/core/src/main/java/software/amazon/smithy/python/codegen/generators/ConfigGenerator.java

@@ -219,7 +219,7 @@ private static void writeDefaultHttpAuthSchemes(GenerationContext context, Pytho
         var supportedAuthSchemes = new LinkedHashMap<String, Symbol>();
         var service = context.settings().service(context.model());
         for (PythonIntegration integration : context.integrations()) {
-            for (RuntimeClientPlugin plugin : integration.getClientPlugins()) {
+            for (RuntimeClientPlugin plugin : integration.getClientPlugins(context)) {
                 if (plugin.matchesService(context.model(), service)
                         && plugin.getAuthScheme().isPresent()
                         && plugin.getAuthScheme().get().getApplicationProtocol().isHttpProtocol()) {
@@ -289,7 +289,7 @@ private void writeInterceptorsType(PythonWriter writer) {
     }
 
     private void generateConfig(GenerationContext context, PythonWriter writer) {
-        var symbol = CodegenUtils.getConfigSymbol(context.settings());
+        var configSymbol = CodegenUtils.getConfigSymbol(context.settings());
 
         // Initialize the list of config properties with our base properties. Here a new
         // list is constructed because that base list is immutable.
@@ -312,7 +312,7 @@ private void generateConfig(GenerationContext context, PythonWriter writer) {
 
         // Add any relevant config properties from plugins.
         for (PythonIntegration integration : context.integrations()) {
-            for (RuntimeClientPlugin plugin : integration.getClientPlugins()) {
+            for (RuntimeClientPlugin plugin : integration.getClientPlugins(context)) {
                 if (plugin.matchesService(model, service)) {
                     properties.addAll(plugin.getConfigProperties());
                 }
@@ -324,7 +324,7 @@ private void generateConfig(GenerationContext context, PythonWriter writer) {
         writer.addStdlibImport("dataclasses", "dataclass");
         writer.write("""
                 @dataclass(init=False)
-                class $L:
+                class $T:
                     \"""Configuration for $L.\"""
 
                     ${C|}
@@ -340,7 +340,7 @@ def __init__(
                         \"""
                         ${C|}
                 """,
-                symbol.getName(),
+                configSymbol,
                 context.settings().service().getName(),
                 writer.consumer(w -> writePropertyDeclarations(w, finalProperties)),
                 writer.consumer(w -> writeInitParams(w, finalProperties)),

codegen/core/src/main/java/software/amazon/smithy/python/codegen/integrations/HttpApiKeyAuth.java

@@ -24,7 +24,7 @@ public final class HttpApiKeyAuth implements PythonIntegration {
     private static final String OPTION_GENERATOR_NAME = "_generate_api_key_option";
 
     @Override
-    public List<RuntimeClientPlugin> getClientPlugins() {
+    public List<RuntimeClientPlugin> getClientPlugins(GenerationContext context) {
         return List.of(
                 RuntimeClientPlugin.builder()
                         .servicePredicate((model, service) -> service.hasTrait(HttpApiKeyAuthTrait.class))

codegen/core/src/main/java/software/amazon/smithy/python/codegen/integrations/PythonIntegration.java

@@ -35,7 +35,7 @@ default List<ProtocolGenerator> getProtocolGenerators() {
      *
      * @return Returns the list of RuntimePlugins to apply to the client.
      */
-    default List<RuntimeClientPlugin> getClientPlugins() {
+    default List<RuntimeClientPlugin> getClientPlugins(GenerationContext context) {
         return Collections.emptyList();
     }
 }

codegen/core/src/main/java/software/amazon/smithy/python/codegen/integrations/RuntimeClientPlugin.java

@@ -16,6 +16,7 @@
 import software.amazon.smithy.model.shapes.OperationShape;
 import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.python.codegen.ConfigProperty;
+import software.amazon.smithy.python.codegen.GenerationContext;
 import software.amazon.smithy.utils.SmithyBuilder;
 import software.amazon.smithy.utils.SmithyUnstableApi;
 import software.amazon.smithy.utils.ToSmithyBuilder;
@@ -38,6 +39,7 @@ public final class RuntimeClientPlugin implements ToSmithyBuilder<RuntimeClientP
     private final OperationPredicate operationPredicate;
     private final List<ConfigProperty> configProperties;
     private final SymbolReference pythonPlugin;
+    private final WriteAdditionalFiles writeAdditionalFiles;
 
     private final AuthScheme authScheme;
 
@@ -47,6 +49,7 @@ private RuntimeClientPlugin(Builder builder) {
         configProperties = Collections.unmodifiableList(builder.configProperties);
         this.pythonPlugin = builder.pythonPlugin;
         this.authScheme = builder.authScheme;
+        this.writeAdditionalFiles = builder.writeAdditionalFiles;
     }
 
     /**
@@ -65,6 +68,20 @@ public interface OperationPredicate {
         boolean test(Model model, ServiceShape service, OperationShape operation);
     }
 
+    @FunctionalInterface
+    /**
+     * Called to write out additional files.
+     */
+    public interface WriteAdditionalFiles {
+        /**
+         * Called to write out additional files needed by a generator.
+         *
+         * @param context GenerationContext - allows access to file manifest and symbol providers
+         * @return List of the relative paths of files written.
+         */
+        List<String> writeAdditionalFiles(GenerationContext context);
+    }
+
     /**
      * Returns true if this plugin applies to the given service.
      *
@@ -120,6 +137,16 @@ public Optional<AuthScheme> getAuthScheme() {
         return Optional.ofNullable(authScheme);
     }
 
+    /**
+     * Write additional files required by this plugin.
+     *
+     * @param context generation context
+     * @return relative paths of additional files written.
+     */
+    public List<String> writeAdditionalFiles(GenerationContext context) {
+        return writeAdditionalFiles.writeAdditionalFiles(context);
+    }
+
     /**
      * @return Returns a new builder for a {@link RuntimeClientPlugin}.
      */
@@ -132,7 +159,8 @@ public SmithyBuilder<RuntimeClientPlugin> toBuilder() {
         var builder = builder()
                 .pythonPlugin(pythonPlugin)
                 .authScheme(authScheme)
-                .configProperties(configProperties);
+                .configProperties(configProperties)
+                .writeAdditionalFiles(writeAdditionalFiles);
 
         if (operationPredicate == OPERATION_ALWAYS_FALSE) {
             builder.servicePredicate(servicePredicate);
@@ -152,6 +180,7 @@ public static final class Builder implements SmithyBuilder<RuntimeClientPlugin>
         private List<ConfigProperty> configProperties = new ArrayList<>();
         private SymbolReference pythonPlugin = null;
         private AuthScheme authScheme = null;
+        private WriteAdditionalFiles writeAdditionalFiles = (context) -> Collections.emptyList();
 
         Builder() {}
 
@@ -264,5 +293,16 @@ public Builder authScheme(AuthScheme authScheme) {
             this.authScheme = authScheme;
             return this;
         }
+
+        /**
+         * Write additional files required by this plugin.
+         *
+         * @param writeAdditionalFiles additional files to write.
+         * @return Returns the builder.
+         */
+        public Builder writeAdditionalFiles(WriteAdditionalFiles writeAdditionalFiles) {
+            this.writeAdditionalFiles = writeAdditionalFiles;
+            return this;
+        }
     }
 }