py-serverless-kit 0.1.1__tar.gz → 0.1.3__tar.gz

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/.gitignore

@@ -1,28 +1,29 @@
-# Python
-__pycache__/
-*.py[cod]
-*.egg-info/
-.venv/
-venv/
-build/
-dist/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-.coverage
-htmlcov/
-.pypirc
-# py-serverless-kit working dirs (local terraform state, artifacts)
-.pskit/
-.terraform/
-*.tfstate
-*.tfstate.*
-
-# Secrets
-.env
-.pypirc
-
-# Editors / OS
-.idea/
-.vscode/
-.DS_Store
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+CLAUDE.md
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.pypirc
+# py-serverless-kit working dirs (local terraform state, artifacts)
+.pskit/
+.terraform/
+*.tfstate
+*.tfstate.*
+
+# Secrets
+.env
+.pypirc
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/CHANGELOG.md

@@ -1,34 +1,52 @@
-# Changelog
-
-All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
-
-> The function runtime is bundled into every deployment. After upgrading `py-serverless-kit`, run `pskit deploy` again to pick up runtime fixes.
-
-## [Unreleased]
-
-## [0.1.1] - 2026-10-15
-
-### Changed
-- Author and maintainer set to Asif Khan @ Kavion.ai (`py_serverless_kit.__author__`, package metadata, LICENSE).
-- Project URLs (homepage, docs, issues, changelog) now point to https://github.com/ak9347128658/serverless_kit.
-- README links are absolute so they work on the PyPI project page; added CI/PyPI/license badges.
-- `scripts/validate_all_providers.py` explains that Terraform is optional instead of printing a traceback when it isn't installed.
-
-### Added
-- `deploy_docs/How_to_deploy.md`: short PyPI release guide with PowerShell commands and troubleshooting (e.g. TestPyPI `403`).
-- `deploy_docs/HOW_TO_INSTALL_TERRAFORM.md`: installing Terraform on Windows.
-
-No runtime changes: functions deployed with 0.1.0 don't need to be redeployed.
-
-## [0.1.0] - 2026-10-15
-
-### Added
-- Portable handler API: `Event`, `HttpRequest`, `Record`, `Headers`, `Context`, `Response`, HTTP error classes, `BatchResult`, `invoke()`.
-- `pskit.yml` configuration with `extends:`, `providers:` and `stages:` overrides, and `${env:}`, `${opt:}`, `${self:}`, `${file()}` and `${tf:}` variables.
-- Providers: AWS (stable), Google Cloud (stable), Azure (stable), Alibaba Cloud (beta), Huawei Cloud (beta), Tencent Cloud (beta), DigitalOcean (beta), IBM Cloud (beta), Oracle Cloud (experimental), Cloudflare Workers (experimental).
-- Triggers: HTTP (path params, CORS, auth), schedule (rate/cron), queue, storage, topic.
-- Workflows: native AWS Step Functions and Google Cloud Workflows compilers, plus an embedded engine for the other providers and local runs.
-- CLI: `init`, `validate`, `package`, `plan`, `deploy`, `remove`, `info`, `dashboard`, `dev`, `invoke`, `workflow run|show`, `providers`, `tf`.
-- Deployment dashboard (self-contained HTML).
-- Local dev server with hot reload, and `LocalRunner` for tests.
-- `scripts/validate_all_providers.py`, which runs `terraform validate` for every provider.
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+> The function runtime is bundled into every deployment. After upgrading `py-serverless-kit`, run `pskit deploy` again to pick up runtime fixes.
+
+## [Unreleased]
+
+## [0.1.3] - 2026-10-15
+
+### Fixed
+- AWS: `pskit deploy` failed with `creating Lambda Function ...: decomposing request: bufio.Scanner: token too long` once the bundle (e.g. with vendored dependencies) got large, because the zip was sent inline in every `CreateFunction` request. The artifact is now uploaded once to S3 (`aws_s3_object`) and each Lambda function references it via `s3_bucket`/`s3_key`. This also lifts the 50 MB inline upload limit.
+
+### Added
+- AWS options `artifact_bucket` (use an existing bucket for code uploads instead of the private `<service>-<stage>-code-*` bucket pskit creates) and `artifact_upload: s3 | direct` (`direct` restores the old inline upload).
+
+No runtime changes. Existing AWS deployments get a new code bucket on the next `pskit deploy`; Lambda functions are updated in place.
+
+## [0.1.2] - 2026-10-15
+
+### Fixed
+- Python 3.9 support: `pskit package`/`deploy` (and the Cloudflare provider) crashed with `TypeError: write_text() got an unexpected keyword argument 'newline'`, because `Path.write_text(newline=...)` only exists on Python 3.10+. Generated files are now written as UTF-8 bytes with `\n` line endings on every Python version.
+- GCP adapter: the storage object `size` check now narrows `None` explicitly, so mypy passes on Python 3.9 CI. Runtime behavior is unchanged.
+
+No runtime behavior changes: functions deployed with 0.1.1 don't need to be redeployed.
+
+## [0.1.1] - 2026-10-15
+
+### Changed
+- Author and maintainer set to Asif Khan @ Kavion.ai (`py_serverless_kit.__author__`, package metadata, LICENSE).
+- Project URLs (homepage, docs, issues, changelog) now point to https://github.com/ak9347128658/serverless_kit.
+- README links are absolute so they work on the PyPI project page; added CI/PyPI/license badges.
+- `scripts/validate_all_providers.py` explains that Terraform is optional instead of printing a traceback when it isn't installed.
+
+### Added
+- `deploy_docs/How_to_deploy.md`: short PyPI release guide with PowerShell commands and troubleshooting (e.g. TestPyPI `403`).
+- `deploy_docs/HOW_TO_INSTALL_TERRAFORM.md`: installing Terraform on Windows.
+
+No runtime changes: functions deployed with 0.1.0 don't need to be redeployed.
+
+## [0.1.0] - 2026-10-15
+
+### Added
+- Portable handler API: `Event`, `HttpRequest`, `Record`, `Headers`, `Context`, `Response`, HTTP error classes, `BatchResult`, `invoke()`.
+- `pskit.yml` configuration with `extends:`, `providers:` and `stages:` overrides, and `${env:}`, `${opt:}`, `${self:}`, `${file()}` and `${tf:}` variables.
+- Providers: AWS (stable), Google Cloud (stable), Azure (stable), Alibaba Cloud (beta), Huawei Cloud (beta), Tencent Cloud (beta), DigitalOcean (beta), IBM Cloud (beta), Oracle Cloud (experimental), Cloudflare Workers (experimental).
+- Triggers: HTTP (path params, CORS, auth), schedule (rate/cron), queue, storage, topic.
+- Workflows: native AWS Step Functions and Google Cloud Workflows compilers, plus an embedded engine for the other providers and local runs.
+- CLI: `init`, `validate`, `package`, `plan`, `deploy`, `remove`, `info`, `dashboard`, `dev`, `invoke`, `workflow run|show`, `providers`, `tf`.
+- Deployment dashboard (self-contained HTML).
+- Local dev server with hot reload, and `LocalRunner` for tests.
+- `scripts/validate_all_providers.py`, which runs `terraform validate` for every provider.

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/CONTRIBUTING.md

@@ -1,13 +1,13 @@
-# Contributing
-
-The full contributor guide lives in [deploy_docs/CONTRIBUTING.md](deploy_docs/CONTRIBUTING.md). It covers the project layout, dev setup, how to add providers and options, and how to verify Terraform.
-
-Maintainers releasing to PyPI: see [deploy_docs/PUBLISHING_TO_PYPI.md](deploy_docs/PUBLISHING_TO_PYPI.md).
-
-Quick start:
-
-```bash
-python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
-pip install -e ".[dev]"
-pytest && ruff check src tests && mypy
-```
+# Contributing
+
+The full contributor guide lives in [deploy_docs/CONTRIBUTING.md](deploy_docs/CONTRIBUTING.md). It covers the project layout, dev setup, how to add providers and options, and how to verify Terraform.
+
+Maintainers releasing to PyPI: see [deploy_docs/PUBLISHING_TO_PYPI.md](deploy_docs/PUBLISHING_TO_PYPI.md).
+
+Quick start:
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+pytest && ruff check src tests && mypy
+```

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Asif Khan @ Kavion.ai
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Asif Khan @ Kavion.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: py-serverless-kit
-Version: 0.1.1
+Version: 0.1.3
 Summary: Write a Python serverless function once and deploy it to AWS, Azure, GCP and 7 more clouds with one YAML file, powered by Terraform.
 Project-URL: Homepage, https://github.com/ak9347128658/serverless_kit
 Project-URL: Documentation, https://github.com/ak9347128658/serverless_kit/tree/main/docs

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/deploy_docs/CONTRIBUTING.md

@@ -1,158 +1,158 @@
-# Contributing to py-serverless-kit
-
-Thanks for helping! This guide explains how the project is organised, how to set up a dev environment, the rules every change has to follow, and step-by-step recipes for the most common contributions: a new event option, a new cloud provider, docs and examples.
-
-## Ground rules
-
-1. **Handler code must never need to change between clouds.** Every feature is designed around this promise. If something can't be portable, it goes under a provider's `options:` and is documented as provider-specific.
-2. **The runtime is standard-library only and Python 3.9 compatible.** Everything in `src/py_serverless_kit/runtime/` is copied into every deployment bundle and runs on clouds we don't control. No third-party imports, no `match` statements, and no `X | Y` type syntax evaluated at runtime. `tests/test_packaging.py::test_vendored_runtime_is_stdlib_only` enforces this.
-3. **Generated Terraform must be real.** Never guess a resource type or argument. Validate with `terraform validate` against the actual provider plugin (see *Verifying Terraform* below).
-4. **Be honest about limits.** If a provider can't do something, raise a clear validation `Issue` and document it. Don't silently skip it.
-5. **Tests come with every change.** Bug fixes need a regression test.
-
-## Project layout
-
-```
-src/py_serverless_kit/
-  runtime/            # shipped inside every function bundle (stdlib only)
-    event.py          #   Event / HttpRequest / Record / Headers
-    response.py       #   Response + coercion of handler return values
-    context.py        #   Context (request id, logger, remaining time)
-    dispatch.py       #   calls the user handler: routing, CORS, error mapping
-    workflow.py       #   embedded state-machine engine
-    invoke.py         #   portable function-to-function invoke()
-    adapters/<cloud>.py  # native event/response <-> portable model
-  config/             # pskit.yml schema (pydantic) + loader (extends, overrides, variables)
-  providers/          # one Terraform renderer per cloud + base class + registry
-  workflows/          # compilers: ASL (AWS Step Functions), Google Cloud Workflows
-  packaging/          # deterministic zip builder
-  terraform/          # terraform/tofu subprocess wrapper
-  core/               # Project (config + provider), Deployer, deployment record
-  local/              # LocalRunner (invoke/workflows) + `pskit dev` server
-  dashboard/          # static HTML dashboard generator
-  cli/                # click CLI + `pskit init` templates
-tests/                # mirrors the package layout
-examples/             # runnable scenario projects (tested by tests/test_examples.py)
-docs/                 # user documentation
-deploy_docs/          # maintainer docs (publishing, contributing)
-```
-
-### How a deploy flows through the code
-
-```
-pskit deploy
-  -> config.loader.load_config       read YAML, extends, providers:/stages: overrides, ${...} variables
-  -> core.project.Project            pick provider, add embedded-workflow orchestrator functions
-  -> Provider.validate               capability / limit checks -> Issues
-  -> packaging.build_artifact        sources + vendored runtime + manifest + provider shim -> artifact.zip
-  -> Provider.render                 TerraformDoc -> .pskit/<provider>-<stage>/main.tf.json
-  -> terraform init/apply            TerraformRunner
-  -> core.describe.build_record      terraform outputs -> deployment.json
-  -> dashboard.write_dashboard       .pskit/dashboard/index.html
-```
-
-At runtime in the cloud:
-
-```
-platform -> shim (e.g. pskit_entry.handler) -> runtime.adapters.<cloud> -> runtime.dispatch.execute -> your handler
-```
-
-## Development setup
-
-```bash
-git clone https://github.com/ak9347128658/serverless_kit.git
-cd serverless_kit
-python -m venv .venv
-source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
-pip install -e ".[dev]"
-pytest                             # whole suite, no cloud access needed
-ruff check src tests
-mypy
-```
-
-Optional tools:
-
-- **Terraform ≥ 1.5** or **OpenTofu**, for `terraform validate` and real deploys.
-- Cloud CLIs/credentials, only if you want to run a real deploy of the examples.
-
-## Workflow
-
-1. Open an issue first for anything non-trivial (new provider, config changes) so we can agree on the design.
-2. Fork and branch from `main`: `feat/<short-name>`, `fix/<short-name>`, `docs/<short-name>`.
-3. Keep PRs focused. One provider or one feature per PR.
-4. Use [Conventional Commits](https://www.conventionalcommits.org/) messages: `feat(gcp): support Cloud Tasks queues`, `fix(runtime): keep multi-value headers`.
-5. Add an entry under **Unreleased** in `CHANGELOG.md`.
-6. Make sure CI is green: tests on Python 3.9 to 3.13, ruff, mypy, and `terraform validate` for every provider.
-7. A maintainer reviews the PR. Expect questions about portability and failure modes.
-
-## Recipes
-
-### Add a new option to an existing event type
-
-Example: `queue.max_concurrency`.
-
-1. Add the field to the model in `config/schema.py` (with a sensible default and validation).
-2. Implement it in every provider that can support it (`providers/<cloud>.py`). Where a provider can't, either ignore it with a `doc.warnings.append(...)` or return an `Issue("error", ...)` from `extra_validation` if ignoring it would be dangerous.
-3. Add tests in `tests/config/test_schema.py` and the relevant `tests/providers/test_<cloud>.py`.
-4. Document it in `docs/configuration.md` and, if it differs per provider, in `docs/providers.md`.
-
-### Add a new cloud provider
-
-1. **Research.** Find the Terraform provider and the exact resources for: a function from a zip (or image), an HTTP endpoint, and triggers. Write down the native event payload shapes and the entrypoint signature.
-2. **Adapter:** create `runtime/adapters/<cloud>.py` with:
-   - `to_event(native, native_ctx) -> Event`: handle HTTP, every trigger type, and `__pskit` envelopes (`adapters.base.unwrap_envelope`);
-   - a function that turns the result into the native response (for HTTP use `Response.render_for_gateway()`);
-   - an entrypoint that calls `runtime.dispatch.execute`.
-3. **Provider:** create `providers/<cloud>.py` subclassing `providers.base.Provider`:
-   - class attributes: `name`, `display_name`, `tier` (`experimental` until it has been deployed for real), `terraform_source`, `default_region`, `capabilities`, `runtimes`, `max_timeout`, `vendor_dependencies`, naming rules;
-   - `shim_files()`: the files at the bundle root that the platform calls;
-   - `render_resources(doc, ctx)`: emit resources, and **always** the `pskit` output (`functions`, `workflows`, `endpoint`);
-   - `extra_validation()` for provider-specific limits.
-4. **Register** it in `providers/registry.py` (`BUILTIN`) and add its name to `PROVIDERS` in `config/schema.py`. Third-party packages can instead register through the `py_serverless_kit.providers` entry-point group without changing this repo:
-
-   ```toml
-   [project.entry-points."py_serverless_kit.providers"]
-   mycloud = "pskit_mycloud:MyCloudProvider"
-   ```
-
-5. **Tests:** `tests/providers/test_<cloud>.py` (render, outputs, validation errors) and `tests/runtime/test_adapter_<cloud>.py` (realistic native payloads, recorded from the real platform when possible).
-6. **Verify Terraform** (below), then update `docs/providers.md`, the README matrix, and `cli/templates.py` (`DEFAULT_REGIONS`, `PROVIDER_OPTIONS`).
-
-### Add an example
-
-Create `examples/NN-name/` with `pskit.yml`, handler code and a `README.md`. `tests/test_examples.py` picks it up automatically and validates and packages it.
-
-## Verifying Terraform
-
-Unit tests check the *shape* of the generated JSON. Only Terraform itself can say whether the resources and arguments exist. For any provider change:
-
-```bash
-cd examples/08-multi-cloud
-pskit package --skip-deps --provider <cloud>
-cd .pskit/<cloud>-dev
-terraform init -backend=false
-terraform validate          # must print: Success! The configuration is valid.
-```
-
-To look up a resource's exact schema:
-
-```bash
-terraform providers schema -json | python -c "import json,sys; s=json.load(sys.stdin); \
-print(json.dumps(next(iter(s['provider_schemas'].values()))['resource_schemas']['aws_lambda_function'], indent=1))"
-```
-
-## Coding style
-
-- `ruff` for linting and import order, line length 120.
-- Type hints everywhere. `mypy` must pass.
-- Comments explain *why*, not *what*. Match the density of the surrounding code.
-- User-facing errors say what's wrong **and** how to fix it.
-
-## Reporting bugs and security issues
-
-- Bugs: open a GitHub issue with `pskit --version`, the provider, the relevant part of `pskit.yml` (remove secrets) and the full error.
-- Security vulnerabilities: **don't** open a public issue. Follow `SECURITY.md`.
-
-## Releasing
-
-Maintainers: see [PUBLISHING_TO_PYPI.md](PUBLISHING_TO_PYPI.md).
+# Contributing to py-serverless-kit
+
+Thanks for helping! This guide explains how the project is organised, how to set up a dev environment, the rules every change has to follow, and step-by-step recipes for the most common contributions: a new event option, a new cloud provider, docs and examples.
+
+## Ground rules
+
+1. **Handler code must never need to change between clouds.** Every feature is designed around this promise. If something can't be portable, it goes under a provider's `options:` and is documented as provider-specific.
+2. **The runtime is standard-library only and Python 3.9 compatible.** Everything in `src/py_serverless_kit/runtime/` is copied into every deployment bundle and runs on clouds we don't control. No third-party imports, no `match` statements, and no `X | Y` type syntax evaluated at runtime. `tests/test_packaging.py::test_vendored_runtime_is_stdlib_only` enforces this.
+3. **Generated Terraform must be real.** Never guess a resource type or argument. Validate with `terraform validate` against the actual provider plugin (see *Verifying Terraform* below).
+4. **Be honest about limits.** If a provider can't do something, raise a clear validation `Issue` and document it. Don't silently skip it.
+5. **Tests come with every change.** Bug fixes need a regression test.
+
+## Project layout
+
+```
+src/py_serverless_kit/
+  runtime/            # shipped inside every function bundle (stdlib only)
+    event.py          #   Event / HttpRequest / Record / Headers
+    response.py       #   Response + coercion of handler return values
+    context.py        #   Context (request id, logger, remaining time)
+    dispatch.py       #   calls the user handler: routing, CORS, error mapping
+    workflow.py       #   embedded state-machine engine
+    invoke.py         #   portable function-to-function invoke()
+    adapters/<cloud>.py  # native event/response <-> portable model
+  config/             # pskit.yml schema (pydantic) + loader (extends, overrides, variables)
+  providers/          # one Terraform renderer per cloud + base class + registry
+  workflows/          # compilers: ASL (AWS Step Functions), Google Cloud Workflows
+  packaging/          # deterministic zip builder
+  terraform/          # terraform/tofu subprocess wrapper
+  core/               # Project (config + provider), Deployer, deployment record
+  local/              # LocalRunner (invoke/workflows) + `pskit dev` server
+  dashboard/          # static HTML dashboard generator
+  cli/                # click CLI + `pskit init` templates
+tests/                # mirrors the package layout
+examples/             # runnable scenario projects (tested by tests/test_examples.py)
+docs/                 # user documentation
+deploy_docs/          # maintainer docs (publishing, contributing)
+```
+
+### How a deploy flows through the code
+
+```
+pskit deploy
+  -> config.loader.load_config       read YAML, extends, providers:/stages: overrides, ${...} variables
+  -> core.project.Project            pick provider, add embedded-workflow orchestrator functions
+  -> Provider.validate               capability / limit checks -> Issues
+  -> packaging.build_artifact        sources + vendored runtime + manifest + provider shim -> artifact.zip
+  -> Provider.render                 TerraformDoc -> .pskit/<provider>-<stage>/main.tf.json
+  -> terraform init/apply            TerraformRunner
+  -> core.describe.build_record      terraform outputs -> deployment.json
+  -> dashboard.write_dashboard       .pskit/dashboard/index.html
+```
+
+At runtime in the cloud:
+
+```
+platform -> shim (e.g. pskit_entry.handler) -> runtime.adapters.<cloud> -> runtime.dispatch.execute -> your handler
+```
+
+## Development setup
+
+```bash
+git clone https://github.com/ak9347128658/serverless_kit.git
+cd serverless_kit
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+pytest                             # whole suite, no cloud access needed
+ruff check src tests
+mypy
+```
+
+Optional tools:
+
+- **Terraform ≥ 1.5** or **OpenTofu**, for `terraform validate` and real deploys.
+- Cloud CLIs/credentials, only if you want to run a real deploy of the examples.
+
+## Workflow
+
+1. Open an issue first for anything non-trivial (new provider, config changes) so we can agree on the design.
+2. Fork and branch from `main`: `feat/<short-name>`, `fix/<short-name>`, `docs/<short-name>`.
+3. Keep PRs focused. One provider or one feature per PR.
+4. Use [Conventional Commits](https://www.conventionalcommits.org/) messages: `feat(gcp): support Cloud Tasks queues`, `fix(runtime): keep multi-value headers`.
+5. Add an entry under **Unreleased** in `CHANGELOG.md`.
+6. Make sure CI is green: tests on Python 3.9 to 3.13, ruff, mypy, and `terraform validate` for every provider.
+7. A maintainer reviews the PR. Expect questions about portability and failure modes.
+
+## Recipes
+
+### Add a new option to an existing event type
+
+Example: `queue.max_concurrency`.
+
+1. Add the field to the model in `config/schema.py` (with a sensible default and validation).
+2. Implement it in every provider that can support it (`providers/<cloud>.py`). Where a provider can't, either ignore it with a `doc.warnings.append(...)` or return an `Issue("error", ...)` from `extra_validation` if ignoring it would be dangerous.
+3. Add tests in `tests/config/test_schema.py` and the relevant `tests/providers/test_<cloud>.py`.
+4. Document it in `docs/configuration.md` and, if it differs per provider, in `docs/providers.md`.
+
+### Add a new cloud provider
+
+1. **Research.** Find the Terraform provider and the exact resources for: a function from a zip (or image), an HTTP endpoint, and triggers. Write down the native event payload shapes and the entrypoint signature.
+2. **Adapter:** create `runtime/adapters/<cloud>.py` with:
+   - `to_event(native, native_ctx) -> Event`: handle HTTP, every trigger type, and `__pskit` envelopes (`adapters.base.unwrap_envelope`);
+   - a function that turns the result into the native response (for HTTP use `Response.render_for_gateway()`);
+   - an entrypoint that calls `runtime.dispatch.execute`.
+3. **Provider:** create `providers/<cloud>.py` subclassing `providers.base.Provider`:
+   - class attributes: `name`, `display_name`, `tier` (`experimental` until it has been deployed for real), `terraform_source`, `default_region`, `capabilities`, `runtimes`, `max_timeout`, `vendor_dependencies`, naming rules;
+   - `shim_files()`: the files at the bundle root that the platform calls;
+   - `render_resources(doc, ctx)`: emit resources, and **always** the `pskit` output (`functions`, `workflows`, `endpoint`);
+   - `extra_validation()` for provider-specific limits.
+4. **Register** it in `providers/registry.py` (`BUILTIN`) and add its name to `PROVIDERS` in `config/schema.py`. Third-party packages can instead register through the `py_serverless_kit.providers` entry-point group without changing this repo:
+
+   ```toml
+   [project.entry-points."py_serverless_kit.providers"]
+   mycloud = "pskit_mycloud:MyCloudProvider"
+   ```
+
+5. **Tests:** `tests/providers/test_<cloud>.py` (render, outputs, validation errors) and `tests/runtime/test_adapter_<cloud>.py` (realistic native payloads, recorded from the real platform when possible).
+6. **Verify Terraform** (below), then update `docs/providers.md`, the README matrix, and `cli/templates.py` (`DEFAULT_REGIONS`, `PROVIDER_OPTIONS`).
+
+### Add an example
+
+Create `examples/NN-name/` with `pskit.yml`, handler code and a `README.md`. `tests/test_examples.py` picks it up automatically and validates and packages it.
+
+## Verifying Terraform
+
+Unit tests check the *shape* of the generated JSON. Only Terraform itself can say whether the resources and arguments exist. For any provider change:
+
+```bash
+cd examples/08-multi-cloud
+pskit package --skip-deps --provider <cloud>
+cd .pskit/<cloud>-dev
+terraform init -backend=false
+terraform validate          # must print: Success! The configuration is valid.
+```
+
+To look up a resource's exact schema:
+
+```bash
+terraform providers schema -json | python -c "import json,sys; s=json.load(sys.stdin); \
+print(json.dumps(next(iter(s['provider_schemas'].values()))['resource_schemas']['aws_lambda_function'], indent=1))"
+```
+
+## Coding style
+
+- `ruff` for linting and import order, line length 120.
+- Type hints everywhere. `mypy` must pass.
+- Comments explain *why*, not *what*. Match the density of the surrounding code.
+- User-facing errors say what's wrong **and** how to fix it.
+
+## Reporting bugs and security issues
+
+- Bugs: open a GitHub issue with `pskit --version`, the provider, the relevant part of `pskit.yml` (remove secrets) and the full error.
+- Security vulnerabilities: **don't** open a public issue. Follow `SECURITY.md`.
+
+## Releasing
+
+Maintainers: see [PUBLISHING_TO_PYPI.md](PUBLISHING_TO_PYPI.md).

{py_serverless_kit-0.1.1 → py_serverless_kit-0.1.3}/docs/README.md

@@ -1,22 +1,22 @@
-# py-serverless-kit documentation
-
-Write a Python function once, describe its triggers in `pskit.yml`, and deploy it to any of 10 clouds with Terraform. Moving to another cloud means changing `provider.name`. The handler code stays the same.
-
-| Page | What it covers |
-|---|---|
-| [Getting started](getting-started.md) | Install, scaffold a project, run it locally, set up cloud credentials, deploy, inspect, remove |
-| [Configuration reference](configuration.md) | Every `pskit.yml` key, `extends:`, `providers:`/`stages:` overrides, variables, escape hatches |
-| [Events (triggers)](events.md) | `http`, `schedule`, `queue`, `storage`, `topic`, with shorthand forms and per-provider support |
-| [Handler API](handlers.md) | `Event`, `HttpRequest`, `Record`, `Context`, `Response`, errors, `BatchResult`, `invoke()`, logging |
-| [Workflows](workflows.md) | State machines: native AWS Step Functions / GCP Workflows, or the embedded engine anywhere |
-| [Providers](providers.md) | Capability matrix plus one section per cloud: options, credentials, resources, limits |
-| [CLI reference](cli.md) | Every `pskit` command and flag |
-| [Local development](local-development.md) | `pskit dev`, `pskit invoke`, `.env`, testing with `LocalRunner` |
-| [Dashboard](dashboard.md) | The generated HTML index of everything you deployed |
-| [Architecture](architecture.md) | How config becomes Terraform and how the runtime dispatches events; third-party providers |
-| [Migrating from AWS](migrating-from-aws.md) | Moving existing Lambda functions and Step Functions to pskit, then to other clouds |
-| [Troubleshooting & FAQ](troubleshooting.md) | Common errors, provider gotchas, security notes |
-
-Runnable examples for every scenario live in [`../examples`](../examples/README.md).
-
-Maintainers: see [`../deploy_docs/PUBLISHING_TO_PYPI.md`](../deploy_docs/PUBLISHING_TO_PYPI.md) and [`../deploy_docs/CONTRIBUTING.md`](../deploy_docs/CONTRIBUTING.md).
+# py-serverless-kit documentation
+
+Write a Python function once, describe its triggers in `pskit.yml`, and deploy it to any of 10 clouds with Terraform. Moving to another cloud means changing `provider.name`. The handler code stays the same.
+
+| Page | What it covers |
+|---|---|
+| [Getting started](getting-started.md) | Install, scaffold a project, run it locally, set up cloud credentials, deploy, inspect, remove |
+| [Configuration reference](configuration.md) | Every `pskit.yml` key, `extends:`, `providers:`/`stages:` overrides, variables, escape hatches |
+| [Events (triggers)](events.md) | `http`, `schedule`, `queue`, `storage`, `topic`, with shorthand forms and per-provider support |
+| [Handler API](handlers.md) | `Event`, `HttpRequest`, `Record`, `Context`, `Response`, errors, `BatchResult`, `invoke()`, logging |
+| [Workflows](workflows.md) | State machines: native AWS Step Functions / GCP Workflows, or the embedded engine anywhere |
+| [Providers](providers.md) | Capability matrix plus one section per cloud: options, credentials, resources, limits |
+| [CLI reference](cli.md) | Every `pskit` command and flag |
+| [Local development](local-development.md) | `pskit dev`, `pskit invoke`, `.env`, testing with `LocalRunner` |
+| [Dashboard](dashboard.md) | The generated HTML index of everything you deployed |
+| [Architecture](architecture.md) | How config becomes Terraform and how the runtime dispatches events; third-party providers |
+| [Migrating from AWS](migrating-from-aws.md) | Moving existing Lambda functions and Step Functions to pskit, then to other clouds |
+| [Troubleshooting & FAQ](troubleshooting.md) | Common errors, provider gotchas, security notes |
+
+Runnable examples for every scenario live in [`../examples`](../examples/README.md).
+
+Maintainers: see [`../deploy_docs/PUBLISHING_TO_PYPI.md`](../deploy_docs/PUBLISHING_TO_PYPI.md) and [`../deploy_docs/CONTRIBUTING.md`](../deploy_docs/CONTRIBUTING.md).