Skip to content

Commit

Permalink
docs: improve Lambda import names
Browse files Browse the repository at this point in the history
In the `aws-lambda-nodejs`, `aws-lambda-python`, and `aws-lambda-go`
package `README`s, the code examples use `lambda` as the name to import
the package. This makes the code examples confusing because
`rosetta/default.ts-fixture` masks the `import` statement from readers
and may confuse them as to why their `lambda` import doesn't work when
they use `lambda.NodejsFunction` (or similar). The imports are changed
to `nodejs`, `python`, and `go`. While the last (`go`) is in fact a
keyword in its own language, so too is `lambda` in Python. This matches
the pattern used by other packages' examples (`aws-route53-patterns` for
example uses `patterns` as the name for its import in docs).

This change should make the docs more clear to new users, who likely
started using Lambda using `lambda.Function` and already have a `lambda`
import that won't do what they want.
  • Loading branch information
laurelmay committed Sep 13, 2022
1 parent 6b7ad6b commit fb05080
Show file tree
Hide file tree
Showing 6 changed files with 33 additions and 33 deletions.
12 changes: 6 additions & 6 deletions packages/@aws-cdk/aws-lambda-go/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ using a Go version >= 1.11 and is using [Go modules](https://golang.org/ref/mod)
Define a `GoFunction`:

```ts
new lambda.GoFunction(this, 'handler', {
new go.GoFunction(this, 'handler', {
entry: 'app/cmd/api',
});
```
Expand Down Expand Up @@ -112,7 +112,7 @@ By default the following environment variables are set for you:
Use the `environment` prop to define additional environment variables when go runs:

```ts
new lambda.GoFunction(this, 'handler', {
new go.GoFunction(this, 'handler', {
entry: 'app/cmd/api',
bundling: {
environment: {
Expand All @@ -138,7 +138,7 @@ To force bundling in a docker container even if `Go` is available in your enviro
Use the `buildArgs` prop to pass build arguments when building the bundling image:

```ts
new lambda.GoFunction(this, 'handler', {
new go.GoFunction(this, 'handler', {
entry: 'app/cmd/api',
bundling: {
buildArgs: {
Expand All @@ -151,7 +151,7 @@ new lambda.GoFunction(this, 'handler', {
Use the `bundling.dockerImage` prop to use a custom bundling image:

```ts
new lambda.GoFunction(this, 'handler', {
new go.GoFunction(this, 'handler', {
entry: 'app/cmd/api',
bundling: {
dockerImage: DockerImage.fromBuild('/path/to/Dockerfile'),
Expand All @@ -162,7 +162,7 @@ new lambda.GoFunction(this, 'handler', {
Use the `bundling.goBuildFlags` prop to pass additional build flags to `go build`:

```ts
new lambda.GoFunction(this, 'handler', {
new go.GoFunction(this, 'handler', {
entry: 'app/cmd/api',
bundling: {
goBuildFlags: ['-ldflags "-s -w"'],
Expand All @@ -177,7 +177,7 @@ It is possible to run additional commands by specifying the `commandHooks` prop
```text
// This example only available in TypeScript
// Run additional commands on a GoFunction via `commandHooks` property
new lambda.GoFunction(this, 'handler', {
new go.GoFunction(this, 'handler', {
bundling: {
commandHooks: {
// run tests
Expand Down
2 changes: 1 addition & 1 deletion packages/@aws-cdk/aws-lambda-go/rosetta/default.ts-fixture
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// Fixture with packages imported, but nothing else
import { Construct } from 'constructs';
import { DockerImage, Stack } from '@aws-cdk/core';
import * as lambda from '@aws-cdk/aws-lambda-go';
import * as go from '@aws-cdk/aws-lambda-go';

class Fixture extends Stack {
constructor(scope: Construct, id: string) {
Expand Down
32 changes: 16 additions & 16 deletions packages/@aws-cdk/aws-lambda-nodejs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ id to look up the entry file. In `my-construct.ts` above we have:

```ts
// automatic entry look up
const apiHandler = new lambda.NodejsFunction(this, 'api');
const authHandler = new lambda.NodejsFunction(this, 'auth');
const apiHandler = new nodejs.NodejsFunction(this, 'api');
const authHandler = new nodejs.NodejsFunction(this, 'auth');
```

Alternatively, an entry file and handler can be specified:

```ts
new lambda.NodejsFunction(this, 'MyFunction', {
new nodejs.NodejsFunction(this, 'MyFunction', {
entry: '/path/to/my/file.ts', // accepts .js, .jsx, .ts, .tsx and .mjs files
handler: 'myExportedFunc', // defaults to 'handler'
});
Expand Down Expand Up @@ -134,7 +134,7 @@ By default, all node modules are bundled except for `aws-sdk`. This can be confi
`bundling.externalModules`:

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
externalModules: [
'aws-sdk', // Use the 'aws-sdk' available in the Lambda runtime
Expand All @@ -152,7 +152,7 @@ bundled but instead included in the `node_modules` folder of the Lambda package.
when working with native dependencies or when `esbuild` fails to bundle a module.

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
nodeModules: ['native-module', 'other-module'],
},
Expand All @@ -174,11 +174,11 @@ The `NodejsFunction` construct exposes [esbuild options](https://esbuild.github.
via properties under `bundling`:

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
minify: true, // minify code, defaults to false
sourceMap: true, // include source map, defaults to false
sourceMapMode: lambda.SourceMapMode.INLINE, // defaults to SourceMapMode.DEFAULT
sourceMapMode: nodejs.SourceMapMode.INLINE, // defaults to SourceMapMode.DEFAULT
sourcesContent: false, // do not include original source into source map, defaults to true
target: 'es2020', // target environment for the generated JavaScript code
loader: { // Use the 'dataurl' loader for '.png' files
Expand All @@ -189,14 +189,14 @@ new lambda.NodejsFunction(this, 'my-handler', {
'process.env.PRODUCTION': JSON.stringify(true),
'process.env.NUMBER': JSON.stringify(123),
},
logLevel: lambda.LogLevel.SILENT, // defaults to LogLevel.WARNING
logLevel: nodejs.LogLevel.SILENT, // defaults to LogLevel.WARNING
keepNames: true, // defaults to false
tsconfig: 'custom-tsconfig.json', // use custom-tsconfig.json instead of default,
metafile: true, // include meta file, defaults to false
banner: '/* comments */', // requires esbuild >= 0.9.0, defaults to none
footer: '/* comments */', // requires esbuild >= 0.9.0, defaults to none
charset: lambda.Charset.UTF8, // do not escape non-ASCII characters, defaults to Charset.ASCII
format: lambda.OutputFormat.ESM, // ECMAScript module output format, defaults to OutputFormat.CJS (OutputFormat.ESM requires Node.js 14.x)
charset: nodejs.Charset.UTF8, // do not escape non-ASCII characters, defaults to Charset.ASCII
format: nodejs.OutputFormat.ESM, // ECMAScript module output format, defaults to OutputFormat.CJS (OutputFormat.ESM requires Node.js 14.x)
mainFields: ['module', 'main'], // prefer ECMAScript versions of dependencies
inject: ['./my-shim.js', './other-shim.js'], // allows to automatically replace a global variable with an import from another file
esbuildArgs: { // Pass additional arguments to esbuild
Expand All @@ -214,7 +214,7 @@ It is possible to run additional commands by specifying the `commandHooks` prop:
```text
// This example only available in TypeScript
// Run additional props via `commandHooks`
new lambda.NodejsFunction(this, 'my-handler-with-commands', {
new nodejs.NodejsFunction(this, 'my-handler-with-commands', {
bundling: {
commandHooks: {
beforeBundling(inputDir: string, outputDir: string): string[] {
Expand Down Expand Up @@ -256,7 +256,7 @@ In some cases, `esbuild` may not yet support some newer features of the typescri
In such cases, it is possible to run pre-compilation using `tsc` by setting the `preCompilation` flag.

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
preCompilation: true,
},
Expand All @@ -270,7 +270,7 @@ Note: A [`tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsco
Use `bundling.environment` to define environments variables when `esbuild` runs:

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
environment: {
NODE_ENV: 'production',
Expand All @@ -282,7 +282,7 @@ new lambda.NodejsFunction(this, 'my-handler', {
Use `bundling.buildArgs` to pass build arguments when building the Docker bundling image:

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
buildArgs: {
HTTPS_PROXY: 'https://127.0.0.1:3001',
Expand All @@ -294,7 +294,7 @@ new lambda.NodejsFunction(this, 'my-handler', {
Use `bundling.dockerImage` to use a custom Docker bundling image:

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
dockerImage: DockerImage.fromBuild('/path/to/Dockerfile'),
},
Expand All @@ -314,7 +314,7 @@ By default the asset hash will be calculated based on the bundled output (`Asset
Use the `assetHash` prop to pass a custom hash:

```ts
new lambda.NodejsFunction(this, 'my-handler', {
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
assetHash: 'my-custom-hash',
},
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// Fixture with packages imported, but nothing else
import { Construct } from 'constructs';
import { DockerImage, Stack } from '@aws-cdk/core';
import * as lambda from '@aws-cdk/aws-lambda-nodejs';
import * as nodejs from '@aws-cdk/aws-lambda-nodejs';

class Fixture extends Stack {
constructor(scope: Construct, id: string) {
Expand Down
16 changes: 8 additions & 8 deletions packages/@aws-cdk/aws-lambda-python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ To use this module, you will need to have Docker installed.
Define a `PythonFunction`:

```ts
new lambda.PythonFunction(this, 'MyFunction', {
new python.PythonFunction(this, 'MyFunction', {
entry: '/path/to/my/function', // required
runtime: Runtime.PYTHON_3_8, // required
index: 'my_index.py', // optional, defaults to 'index.py'
Expand All @@ -44,19 +44,19 @@ layer.
Define a `PythonLayerVersion`:

```ts
new lambda.PythonLayerVersion(this, 'MyLayer', {
new python.PythonLayerVersion(this, 'MyLayer', {
entry: '/path/to/my/layer', // point this to your library's directory
})
```

A layer can also be used as a part of a `PythonFunction`:

```ts
new lambda.PythonFunction(this, 'MyFunction', {
new python.PythonFunction(this, 'MyFunction', {
entry: '/path/to/my/function',
runtime: Runtime.PYTHON_3_8,
layers: [
new lambda.PythonLayerVersion(this, 'MyLayer', {
new python.PythonLayerVersion(this, 'MyLayer', {
entry: '/path/to/my/layer', // point this to your library's directory
}),
],
Expand Down Expand Up @@ -123,7 +123,7 @@ Additional build args for bundling that refer to PyPI indexes can be specified a
const entry = '/path/to/function';
const image = DockerImage.fromBuild(entry);

new lambda.PythonFunction(this, 'function', {
new python.PythonFunction(this, 'function', {
entry,
runtime: Runtime.PYTHON_3_8,
bundling: {
Expand All @@ -138,7 +138,7 @@ If using a custom Docker image for bundling, the dependencies are installed with
const entry = '/path/to/function';
const image = DockerImage.fromBuild(entry);

new lambda.PythonFunction(this, 'function', {
new python.PythonFunction(this, 'function', {
entry,
runtime: Runtime.PYTHON_3_8,
bundling: { image },
Expand All @@ -163,7 +163,7 @@ const codeArtifactAuthToken = execSync(`aws codeartifact get-authorization-token

const indexUrl = `https://aws:${codeArtifactAuthToken}@${domain}-${domainOwner}.d.codeartifact.${region}.amazonaws.com/pypi/${repoName}/simple/`;

new lambda.PythonFunction(this, 'function', {
new python.PythonFunction(this, 'function', {
entry,
runtime: Runtime.PYTHON_3_8,
bundling: {
Expand All @@ -190,7 +190,7 @@ const codeArtifactAuthToken = execSync(`aws codeartifact get-authorization-token

const indexUrl = `https://aws:${codeArtifactAuthToken}@${domain}-${domainOwner}.d.codeartifact.${region}.amazonaws.com/pypi/${repoName}/simple/`;

new lambda.PythonFunction(this, 'function', {
new python.PythonFunction(this, 'function', {
entry,
runtime: Runtime.PYTHON_3_8,
bundling: {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
import { Construct } from 'constructs';
import { DockerImage, Stack } from '@aws-cdk/core';
import { Runtime } from '@aws-cdk/aws-lambda';
import * as lambda from '@aws-cdk/aws-lambda-python';
import * as python from '@aws-cdk/aws-lambda-python';

class Fixture extends Stack {
constructor(scope: Construct, id: string) {
Expand Down

0 comments on commit fb05080

Please sign in to comment.