celerity-sdk 0.2.0__tar.gz

celerity_sdk-0.2.0/.env.test

@@ -0,0 +1,5 @@
+AWS_ACCESS_KEY_ID=testing
+AWS_SECRET_ACCESS_KEY=testing
+AWS_DEFAULT_REGION=us-east-1
+AWS_REGION=us-east-1
+AWS_ENDPOINT_URL=http://localhost:4566

celerity_sdk-0.2.0/.githooks/commit-msg

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -e
+
+RED='\033[0;31m'
+NC='\033[0m'
+
+# Use commitlint if available (installed via yarn)
+if command -v npx &> /dev/null && [ -f "node_modules/.bin/commitlint" ]; then
+    npx --no-install commitlint --edit "$1"
+    exit $?
+fi
+
+# Fallback to regex validation if commitlint is not installed
+PATTERN='^(feat|fix|build|revert|wip|chore|ci|docs|style|refactor|perf|test|instr|deps)(\([a-zA-Z0-9_-]+\))?!?: .+'
+
+COMMIT_MSG=$(cat "$1")
+
+# Allow merge commits
+if echo "$COMMIT_MSG" | grep -qE '^Merge '; then
+    exit 0
+fi
+
+if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
+    echo -e "${RED}Invalid commit message format.${NC}"
+    echo ""
+    echo "Expected: type(scope): description"
+    echo "Types: feat, fix, build, revert, wip, chore, ci, docs, style, refactor, perf, test, instr, deps"
+    echo ""
+    echo "Examples:"
+    echo "  feat: add handler pipeline"
+    echo "  fix(di): resolve circular dependency detection"
+    echo "  chore: update dependencies"
+    echo ""
+    exit 1
+fi

celerity_sdk-0.2.0/.githooks/pre-commit

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+echo "Running pre-commit checks..."
+
+# Check if any Python files are staged
+STAGED_PY=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.py$' || true)
+if [ -z "$STAGED_PY" ]; then
+    echo -e "${GREEN}No Python files staged, skipping checks.${NC}"
+    exit 0
+fi
+
+echo "Checking formatting..."
+if ! uv run ruff format --check src/ tests/ 2>/dev/null; then
+    echo -e "${RED}Formatting check failed. Run 'uv run ruff format src/ tests/' to fix.${NC}"
+    exit 1
+fi
+
+echo "Checking lint..."
+if ! uv run ruff check src/ tests/ 2>/dev/null; then
+    echo -e "${RED}Lint check failed. Run 'uv run ruff check --fix src/ tests/' to fix.${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}Pre-commit checks passed.${NC}"

celerity_sdk-0.2.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "04:00"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "github-actions"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "04:00"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"

celerity_sdk-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- Brief description of what this PR does and why. -->
+
+## Changes
+
+-
+
+## Test Plan
+
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated (if applicable)
+- [ ] All tests pass locally (`./scripts/run-tests.sh all`)
+
+## Checklist
+
+- [ ] Code follows project conventions (`uv run ruff check src/ tests/`)
+- [ ] Types are correct (`uv run mypy src/`)
+- [ ] No unnecessary `Any` types introduced
+- [ ] Google-style docstrings on public APIs
+- [ ] Commit messages follow conventional commits format

celerity_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Security audit
+        run: uvx pip-audit
+
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Generate Ruff report for SonarCloud
+        run: uv run ruff check src/ tests/ --output-format json > ruff-report.json || true
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Run all tests with coverage
+        run: ./scripts/run-tests.sh all
+        env:
+          AWS_ACCESS_KEY_ID: testing
+          AWS_SECRET_ACCESS_KEY: testing
+          AWS_DEFAULT_REGION: us-east-1
+          AWS_REGION: us-east-1
+          AWS_ENDPOINT_URL: http://localhost:4566
+
+      - name: SonarCloud Scan
+        uses: SonarSource/sonarqube-scan-action@v7
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

celerity_sdk-0.2.0/.github/workflows/codeql.yml

@@ -0,0 +1,34 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 4 * * 1" # Weekly Monday 4:00 UTC
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: +security-extended
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "codeql-python"

celerity_sdk-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,52 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Manually trigger publish (true/false)"
+        required: false
+        default: "false"
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true' || github.event.inputs.publish == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

celerity_sdk-0.2.0/.github/workflows/security.yml

@@ -0,0 +1,24 @@
+name: Security
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    name: Actions Workflow Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Lint GitHub Actions workflows
+        uses: reviewdog/action-actionlint@v1
+        with:
+          reporter: github-pr-review
+          fail_level: error

celerity_sdk-0.2.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Tool caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Environment files
+.env
+.env.local
+
+# Native extensions
+*.so
+*.dylib
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+uv.lock
+
+# Test reports
+coverage.xml
+test-results.xml
+htmlcov/
+.coverage
+
+# Node (commitlint dev tooling)
+node_modules/
+yarn-error.log
+
+CLAUDE.md
+.claude

celerity_sdk-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

celerity_sdk-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

celerity_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [0.2.0](https://github.com/newstack-cloud/celerity-python-sdk/compare/v0.1.0...v0.2.0) (2026-03-21)
+
+
+### Features
+
+* add bucket resource implementation ([93ba36f](https://github.com/newstack-cloud/celerity-python-sdk/commit/93ba36f50e069ee85c128cb5220dbb46b069fa10))
+* add cache resource implementation ([ddf8279](https://github.com/newstack-cloud/celerity-python-sdk/commit/ddf82792c2595971a9c3889726a2efb2d7e44010))
+* add datastore implementation with dynamodb provider ([1890a8a](https://github.com/newstack-cloud/celerity-python-sdk/commit/1890a8a195ba823c5085b90bd311202d063f15b4))
+* add decorators for all supported features ([1102fd1](https://github.com/newstack-cloud/celerity-python-sdk/commit/1102fd1248017d7a381bfc7646effc752a25ca81))
+* add foundation types, metadata system and common utils ([6b49108](https://github.com/newstack-cloud/celerity-python-sdk/commit/6b491086ba6e400670712331b89ea1dcc4866d3c))
+* add handler infra with registry, scanners, layers, pipelines and bootstrap ([529ca7c](https://github.com/newstack-cloud/celerity-python-sdk/commit/529ca7c3395eea3a5262ad932b8f949ec551fe0a))
+* add handler manifest extraction cli ([f1fed1f](https://github.com/newstack-cloud/celerity-python-sdk/commit/f1fed1fe1123cae4a6b0fa62ddd0726d8593d55b))
+* add instrumentation for dynamodb datastore implementation ([65ab6a5](https://github.com/newstack-cloud/celerity-python-sdk/commit/65ab6a5747efb4f88a238eb36b05602b9918ec95))
+* add instrumentation to redis cache implementation ([99501a4](https://github.com/newstack-cloud/celerity-python-sdk/commit/99501a411b75463af0590d7d5fb81792ff76dc04))
+* add queue resource implementation ([0101e6e](https://github.com/newstack-cloud/celerity-python-sdk/commit/0101e6ea55892738bd967c4ba1a8ff4e83912425))
+* add resource type foundations and config implementation ([bb5b0c4](https://github.com/newstack-cloud/celerity-python-sdk/commit/bb5b0c473732f0079fbc61abcc0dae00b68e29e8))
+* add runtime orchestrator and serverless adapters ([65f4750](https://github.com/newstack-cloud/celerity-python-sdk/commit/65f4750c8a3f55d72d6f111dc5ab6449fdca681b))
+* add sql database resource implementation ([b19a225](https://github.com/newstack-cloud/celerity-python-sdk/commit/b19a22547818e8297d2675bd9070fec902ebfd90))
+* add telemetry foundations ([200b509](https://github.com/newstack-cloud/celerity-python-sdk/commit/200b509fc20552cd08a6d8325a2837b0a2484345))
+* add test utils for building celerity apps ([d4cd647](https://github.com/newstack-cloud/celerity-python-sdk/commit/d4cd647cd585a1ee9f25da7d94f6e744b4261952))
+* add topic resource implementation ([e305526](https://github.com/newstack-cloud/celerity-python-sdk/commit/e3055268847ebf5a0ac40b5d26d6e051968c0f30))
+* complete telemetry implementation ([25863e8](https://github.com/newstack-cloud/celerity-python-sdk/commit/25863e8b2ce68a31592ee60c02517a75b29a8a30))
+* integrate module-level layers ([d0bd44f](https://github.com/newstack-cloud/celerity-python-sdk/commit/d0bd44f79cc60d89feb298d80d43c8cf4ee099cf))
+
+
+### Bug Fixes
+
+* add fixes for ci integration tests and resource backend resolution ([9ee2eb6](https://github.com/newstack-cloud/celerity-python-sdk/commit/9ee2eb654b6856c724a922276da5a29d64a45e1a))
+* add security fix for sql db factory to be secure when ssl is enabled ([939b9a0](https://github.com/newstack-cloud/celerity-python-sdk/commit/939b9a033ae50214928e48c961146d2538c969e5))
+* add type fixes for telemetry ([75ca6c1](https://github.com/newstack-cloud/celerity-python-sdk/commit/75ca6c1c8d52ed86cfed1f915aafd1a9fc077d32))
+* correct bucket resource to resolve bucket name from mappings ([548f3c8](https://github.com/newstack-cloud/celerity-python-sdk/commit/548f3c83a3e67cfb0dd7a4542f4a7d19efacc847))
+* correct cache to take key prefix mappings in client constructor ([86b02b9](https://github.com/newstack-cloud/celerity-python-sdk/commit/86b02b9604f985fb7c9d89c6c801b589f2d5a813))
+* correct data store resource to resolve table name from mappings ([85d8bef](https://github.com/newstack-cloud/celerity-python-sdk/commit/85d8bef3421da434cea7355782f55f161cf74996))
+* correct missing type errors for sqlalchemy ([cfa6634](https://github.com/newstack-cloud/celerity-python-sdk/commit/cfa6634be9cdb778062fc916160b1b6880910460))
+* correct resource injection to use annotated types ([ee60fa6](https://github.com/newstack-cloud/celerity-python-sdk/commit/ee60fa6366e61dea7d5a29447c69bb95681aa9b1))

celerity_sdk-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,174 @@
+# Contributing
+
+## Prerequisites
+
+- Python >= 3.13
+- [uv](https://docs.astral.sh/uv/) >= 0.5
+- Node.js >= 22 (for commitlint only)
+- yarn (for commitlint only)
+- Docker (for integration tests)
+
+## Getting Started
+
+```bash
+# Clone the repository
+git clone git@github.com:newstack-cloud/celerity-python-sdk.git
+cd celerity-python-sdk
+
+# Install Python dependencies (all extras needed for development)
+uv sync --extra dev --extra runtime --extra aws --extra cache
+
+# Install commitlint (Node.js dev tooling)
+yarn install
+
+# Set up git hooks for conventional commits
+git config core.hooksPath .githooks
+
+# Run unit tests
+./scripts/run-tests.sh unit
+
+# Run integration tests
+./scripts/run-tests.sh integration
+
+# Run all tests (unit + integration)
+./scripts/run-tests.sh all
+
+# Run linting and type checking
+uv run ruff check src/ tests/
+uv run mypy src/
+```
+
+## Development
+
+```bash
+# Format code
+uv run ruff format src/ tests/
+
+# Lint with auto-fix
+uv run ruff check --fix src/ tests/
+
+# Type check
+uv run mypy src/
+
+# Run a specific test file
+uv run pytest tests/test_types.py
+
+# Run tests matching a keyword
+uv run pytest -k "test_metadata"
+```
+
+## Managing Dependencies
+
+```bash
+# Add a runtime dependency
+uv add httpx
+
+# Add a dev dependency
+uv add --dev pytest-mock
+
+# Add a dependency to an extra group
+# (edit pyproject.toml [project.optional-dependencies] directly)
+
+# Sync after editing pyproject.toml
+uv sync --extra dev --extra runtime --extra aws --extra cache
+```
+
+## Conventional Commits
+
+This project uses [conventional commits](https://www.conventionalcommits.org/) enforced by commitlint.
+
+Format: `type(scope): description`
+
+**Types**: `feat`, `fix`, `build`, `revert`, `wip`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`, `instr`, `deps`
+
+**Scopes**: `types`, `common`, `metadata`, `decorators`, `di`, `bootstrap`, `handlers`, `layers`, `errors`, `functions`, `testing`, `cli`, `serverless`, `resources`, `telemetry`, `ci`, `repo`, `deps`
+
+Examples:
+```
+feat(handlers): add HTTP handler pipeline
+fix(di): resolve circular dependency detection
+chore: update dependencies
+docs(resources): add datastore usage examples
+test(bootstrap): add module graph integration tests
+```
+
+## Project Structure
+
+```
+src/celerity/          SDK source code (src layout)
+├── types/             Shared data types and ABCs
+├── common/            Shared utilities
+├── metadata/          Metadata storage primitives
+├── decorators/        Handler and parameter decorators
+├── di/                Dependency injection container
+├── bootstrap/         Application bootstrap and module graph
+├── handlers/          Handler registry, scanners, pipelines
+├── layers/            Middleware layer pipeline
+├── errors/            HTTP exceptions
+├── functions/         Function handler factories
+├── testing/           Test utilities (TestApp, mocks)
+├── cli/               Handler manifest extraction CLI
+├── serverless/        Cloud adapters (AWS, GCP, Azure)
+├── resources/         Cloud-agnostic resource clients
+└── telemetry/         Logging and tracing
+tests/                 Test suite
+tests/integration/     Integration tests (require Docker services)
+scripts/               Build and test scripts
+docs/design/           Phase-by-phase design documents
+```
+
+## Testing
+
+Use `scripts/run-tests.sh` to run tests. Coverage and JUnit XML reports are always generated.
+
+```bash
+# Unit tests only (no Docker needed)
+./scripts/run-tests.sh unit
+
+# Integration tests only (starts/stops Docker services)
+./scripts/run-tests.sh integration
+
+# All tests — unit + integration (starts/stops Docker services)
+./scripts/run-tests.sh all
+
+# Pass additional pytest args
+./scripts/run-tests.sh unit -k "test_metadata"
+```
+
+All Docker-dependent commands (`integration`, `all`) handle the full Docker Compose lifecycle automatically — starting services, running tests, and tearing down — so you never need to manage Docker manually.
+
+Reports generated:
+- `coverage.xml` — Cobertura coverage report (consumed by SonarCloud)
+- `test-results.xml` — JUnit test results
+
+To manage Docker services manually for iterative development:
+
+```bash
+# Start services in the background
+docker compose up -d --wait
+
+# Run integration tests directly (services already running)
+uv run pytest tests/integration/
+
+# Stop services
+docker compose down -v
+```
+
+### Docker Services
+
+The `docker-compose.yml` provides:
+
+- **Valkey** (port 6399) — Redis-compatible cache, queue, and topic testing
+- **LocalStack** (port 4566) — AWS service emulation (S3, SQS, SNS, DynamoDB, SSM, Secrets Manager)
+- **PostgreSQL** (port 5499) — SQL database testing
+
+## Code Quality
+
+All checks must pass before merging:
+
+- **Formatting**: `uv run ruff format --check src/ tests/`
+- **Linting**: `uv run ruff check src/ tests/`
+- **Type checking**: `uv run mypy src/`
+- **Tests**: `./scripts/run-tests.sh all`
+
+The pre-commit hook runs format and lint checks automatically on staged Python files.