Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
38200e4
chore: wip
eoinsha Feb 8, 2025
ccfc3a2
chore: wip
eoinsha Feb 9, 2025
56458b5
chore: wip
eoinsha Apr 15, 2026
e6b2caf
chore: use per-synth builder containers
eoinsha Apr 15, 2026
f7d37c0
chore: upgrade with projen
eoinsha Apr 15, 2026
f76d0d0
chore: use absolute paths for mounts
eoinsha Apr 15, 2026
8ac5d72
doc: tidy up and add more examples to README
eoinsha Apr 15, 2026
db52048
chore: normalise test packages to src-based layout
eoinsha Apr 15, 2026
ce6cd2d
chore: update inline docs in builder Dockerfile and entrypoint
eoinsha Apr 15, 2026
7071dfe
test: support running in GHA
eoinsha Apr 15, 2026
f71b7f8
chore: Update AGENTS.md
eoinsha Apr 16, 2026
cf6c7d3
chore: update .github/copilot-instructions.md
eoinsha Apr 16, 2026
4a1c8f2
fix: fail fast when CDK_OUTDIR is unset in PythonFunction metadata
Copilot Apr 16, 2026
8568cf4
feat: allow overriding builder image or base
eoinsha Apr 16, 2026
a36d24a
fix: support pass-through of container runtime opts
eoinsha Apr 16, 2026
fbb60d1
chore: handle different image overrides with some tools installed
eoinsha Apr 16, 2026
38fed9c
chore: update generated API.md
eoinsha Apr 17, 2026
35370f4
fix: cap uv concurrency to prevent ENFILE errors during bundling (#14)
eoinsha-h Apr 17, 2026
454d319
fix: prune old build containers
eoinsha Apr 24, 2026
3e2f397
chore: try providing assets as ZIP
eoinsha May 6, 2026
d7e968d
fix: improve exclusions in bundling, esp. cdk.out nesting
eoinsha May 16, 2026
740d43d
fix(export.sh): resolve stale locks hanging builds
eoinsha Jul 21, 2026
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