Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitattributes

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

32 changes: 32 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# uv-python-lambda Copilot Instructions

## Build, test, and lint

- Install dependencies with `yarn install --check-files` (matches CI).
- Build with `npx projen build`.
- Run the full test suite with `npx projen test`.
- Run a single test file with `npx jest test/function.test.ts`.
- Run a single test case with `npx jest test/function.test.ts -t "Create a function from basic_app"`.
- Lint/format checks use Biome: `npx biome check`.
- To check a specific file with Biome, run `npx biome check src/function.ts`.

## High-level architecture

- This repository is a **projen-managed jsii CDK construct library**. The human-authored sources are mainly in `src/`, `test/`, `resources/`, and `.projenrc.ts`. Generated project files such as `package.json`, GitHub workflows, and packaging config should be changed via `.projenrc.ts` and then regenerated with `npx projen`.
- The public API is exported from `src/index.ts`. The main construct is `PythonFunction` in `src/function.ts`, which extends `aws-cdk-lib/aws-lambda.Function`.
- `PythonFunction` is a thin orchestration layer: it resolves the Lambda handler name from `index` + `handler`, enforces a Python runtime, defaults to `Architecture.ARM_64` and `Runtime.PYTHON_3_12`, and delegates packaging to `Bundling.bundle(...)`.
- `src/bundling.ts` owns packaging. It creates a Docker builder image from `resources/`, caches long-lived builder containers by a hash of runtime/architecture/build args/root dir, and returns Lambda code through `Code.fromCustomCommand(...)` so CDK can stage the packaged asset.
- The Docker-side build flow lives in `resources/entrypoint.sh` and `resources/export.sh`:
- `entrypoint.sh` starts the builder container and keeps it available for later packaging/export work.
- `export.sh` runs later via `docker exec`; it can optionally scope to `--package <workspace>`, exports requirements, and installs dependencies into the requested asset output directory.
- `workspacePackage` is the key monorepo/workspace feature: it tells bundling to treat a specific uv workspace package as the Lambda entry package while still resolving dependencies from the workspace root.
- Tests in `test/function.test.ts` are integration-style CDK packaging tests, not isolated unit tests. They create real CDK apps/stacks, require Docker, use fixture uv projects from `test/resources/`, and inspect the staged asset contents through the custom metadata key `uv-python-lambda:asset-path`.

## Key conventions

- **Do not hand-edit generated project files.** `package.json` explicitly says it is generated by projen, and the workflows under `.github/workflows/` are generated from `.projenrc.ts`.
- **Keep changes aligned with Biome formatting/import ordering.** The repo uses Biome instead of ESLint/Prettier, with single quotes and organize-imports enabled.
- **Preserve jsii-friendly public types.** Public configuration is expressed as exported TypeScript interfaces (`PythonFunctionProps`, `BundlingOptions`, `ICommandHooks`) because this library is packaged for TypeScript and Python consumers.
- **Bundling assumes Docker-based execution.** There is no parallel local packager path; changes to packaging behavior usually involve `src/bundling.ts` plus the shell scripts in `resources/`.
- **Be careful with architecture defaults.** Production code defaults Lambda functions to ARM64, while tests intentionally detect the Docker host architecture to avoid slow QEMU emulation on GitHub runners.
- **Asset metadata is intentional.** `PythonFunction` writes `uv-python-lambda:asset-path` metadata so tests and downstream CDK asset inspection can find the staged bundle.
36 changes: 20 additions & 16 deletions .github/workflows/build.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .github/workflows/pull-request-lint.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

37 changes: 20 additions & 17 deletions .github/workflows/release.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 12 additions & 10 deletions .github/workflows/upgrade-main.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions .gitignore

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions .mergify.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading