lambdaforge-local 0.1.0__py3-none-any.whl

lambdaforge/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

lambdaforge/cli.py

@@ -0,0 +1,116 @@
+import json
+from pathlib import Path
+
+import click
+
+from lambdaforge.events import TRIGGERS
+from lambdaforge.invoker import load_handler, invoke_handler
+from lambdaforge.mocking import SUPPORTED_SERVICES, activated_mocks
+from lambdaforge import output
+
+
+@click.group()
+def cli():
+    """lambdaforge — local AWS Lambda testing made simple."""
+
+
+@cli.command()
+@click.option(
+    "--trigger",
+    required=True,
+    type=click.Choice(list(TRIGGERS.keys())),
+    help="Lambda trigger type",
+)
+@click.option(
+    "--output",
+    "output_path",
+    default="event.json",
+    show_default=True,
+    help="Output file path",
+)
+def generate(trigger: str, output_path: str) -> None:
+    """Generate a base event JSON file for the given trigger type."""
+    event = TRIGGERS[trigger]()
+    path = Path(output_path)
+    path.write_text(json.dumps(event, indent=2))
+    click.echo(f"Event written to {output_path}")
+
+
+@cli.command()
+@click.option(
+    "--handler",
+    "handler_spec",
+    required=True,
+    help="Handler: path/to/file.py::function_name",
+)
+@click.option(
+    "--event",
+    "event_path",
+    default="event.json",
+    show_default=True,
+    help="Event JSON file path",
+)
+@click.option(
+    "--mock",
+    "mock_str",
+    default="",
+    help="Comma-separated AWS services to mock, e.g. dynamodb,s3",
+)
+def invoke(handler_spec: str, event_path: str, mock_str: str) -> None:
+    """Invoke a Lambda handler locally."""
+    # Validate and parse mock services
+    services = [s.strip() for s in mock_str.split(",") if s.strip()]
+    for svc in services:
+        if svc not in SUPPORTED_SERVICES:
+            valid = ", ".join(sorted(SUPPORTED_SERVICES))
+            click.echo(
+                f'Error: unknown service "{svc}". Valid options: {valid}', err=True
+            )
+            raise SystemExit(1)
+
+    # Validate handler path
+    if "::" not in handler_spec:
+        click.echo(
+            "Error: invalid handler format. Use path/to/file.py::function_name",
+            err=True,
+        )
+        raise SystemExit(1)
+    handler_file = handler_spec.split("::")[0]
+    if not Path(handler_file).exists():
+        click.echo(f"Error: handler file not found: {handler_file}", err=True)
+        raise SystemExit(1)
+
+    # Validate event file
+    event_file = Path(event_path)
+    if not event_file.exists():
+        click.echo(f"Error: event file not found: {event_path}", err=True)
+        raise SystemExit(1)
+    try:
+        event = json.loads(event_file.read_text())
+    except json.JSONDecodeError:
+        click.echo(f"Error: event file is not valid JSON: {event_path}", err=True)
+        raise SystemExit(1)
+
+    # Load handler
+    try:
+        handler = load_handler(handler_spec)
+    except Exception as exc:
+        click.echo(f"Error loading handler: {exc}", err=True)
+        raise SystemExit(1)
+
+    output.print_header(handler_spec, event_path, services)
+
+    # Invoke with or without mocks
+    try:
+        if services:
+            with activated_mocks(services):
+                result, logs, duration_ms = invoke_handler(handler, event)
+        else:
+            result, logs, duration_ms = invoke_handler(handler, event)
+    except Exception:
+        output.print_error()
+        raise SystemExit(1)
+
+    output.print_logs(logs)
+    output.print_result(result)
+    output.print_duration(duration_ms)

lambdaforge/events/__init__.py

@@ -0,0 +1,9 @@
+from lambdaforge.events import apigateway, sqs, s3, sns, eventbridge
+
+TRIGGERS: dict = {
+    "apigateway": apigateway.generate,
+    "sqs": sqs.generate,
+    "s3": s3.generate,
+    "sns": sns.generate,
+    "eventbridge": eventbridge.generate,
+}

lambdaforge/events/apigateway.py

@@ -0,0 +1,16 @@
+def generate() -> dict:
+    return {
+        "httpMethod": "GET",
+        "path": "<your-path>",
+        "pathParameters": None,
+        "queryStringParameters": None,
+        "headers": {
+            "Content-Type": "application/json",
+        },
+        "body": "<your-json-body-or-null>",
+        "isBase64Encoded": False,
+        "requestContext": {
+            "stage": "local",
+            "requestId": "local-request-id",
+        },
+    }

lambdaforge/events/eventbridge.py

@@ -0,0 +1,12 @@
+def generate() -> dict:
+    return {
+        "version": "0",
+        "id": "local-event-id",
+        "source": "<your-event-source>",
+        "account": "000000000000",
+        "time": "2024-01-01T00:00:00Z",
+        "region": "us-east-1",
+        "resources": [],
+        "detail-type": "<your-detail-type>",
+        "detail": {},
+    }

lambdaforge/events/s3.py

@@ -0,0 +1,25 @@
+def generate() -> dict:
+    return {
+        "Records": [
+            {
+                "eventVersion": "2.1",
+                "eventSource": "aws:s3",
+                "awsRegion": "us-east-1",
+                "eventTime": "2024-01-01T00:00:00.000Z",
+                "eventName": "ObjectCreated:Put",
+                "s3": {
+                    "s3SchemaVersion": "1.0",
+                    "configurationId": "local",
+                    "bucket": {
+                        "name": "<your-bucket-name>",
+                        "arn": "arn:aws:s3:::<your-bucket-name>",
+                    },
+                    "object": {
+                        "key": "<your-object-key>",
+                        "size": 1024,
+                        "eTag": "local-etag",
+                    },
+                },
+            }
+        ]
+    }

lambdaforge/events/sns.py

@@ -0,0 +1,23 @@
+def generate() -> dict:
+    return {
+        "Records": [
+            {
+                "EventVersion": "1.0",
+                "EventSubscriptionArn": "arn:aws:sns:us-east-1:000000000000:<your-topic-name>:local",
+                "EventSource": "aws:sns",
+                "Sns": {
+                    "SignatureVersion": "1",
+                    "Timestamp": "2024-01-01T00:00:00.000Z",
+                    "Signature": "local-signature",
+                    "SigningCertUrl": "local",
+                    "MessageId": "<your-message-id>",
+                    "Message": "<your-message-body>",
+                    "MessageAttributes": {},
+                    "Type": "Notification",
+                    "UnsubscribeUrl": "local",
+                    "TopicArn": "arn:aws:sns:us-east-1:000000000000:<your-topic-name>",
+                    "Subject": "<your-subject-or-null>",
+                },
+            }
+        ]
+    }

lambdaforge/events/sqs.py

@@ -0,0 +1,21 @@
+def generate() -> dict:
+    return {
+        "Records": [
+            {
+                "messageId": "<your-message-id>",
+                "receiptHandle": "local-receipt-handle",
+                "body": "<your-message-body>",
+                "attributes": {
+                    "ApproximateReceiveCount": "1",
+                    "SentTimestamp": "1640000000000",
+                    "SenderId": "000000000000",
+                    "ApproximateFirstReceiveTimestamp": "1640000000001",
+                },
+                "messageAttributes": {},
+                "md5OfBody": "local-md5",
+                "eventSource": "aws:sqs",
+                "eventSourceARN": "arn:aws:sqs:us-east-1:000000000000:<your-queue-name>",
+                "awsRegion": "us-east-1",
+            }
+        ]
+    }

lambdaforge/invoker.py

@@ -0,0 +1,80 @@
+import importlib.util
+import io
+import logging
+import time
+import uuid
+from contextlib import redirect_stdout
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass
+class LambdaContext:
+    function_name: str = "lambdaforge-local"
+    function_version: str = "$LATEST"
+    invoked_function_arn: str = (
+        "arn:aws:lambda:us-east-1:000000000000:function:lambdaforge-local"
+    )
+    memory_limit_in_mb: int = 128
+    aws_request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    log_group_name: str = "/aws/lambda/lambdaforge-local"
+    log_stream_name: str = "local"
+
+    def get_remaining_time_in_millis(self) -> int:
+        return 30000
+
+
+def load_handler(handler_spec: str) -> Callable:
+    """Load a handler callable from 'path/to/file.py::function_name'.
+
+    The file path is resolved relative to the current working directory.
+    Raises ValueError if the format is invalid, FileNotFoundError if the file
+    does not exist.
+    """
+    if "::" not in handler_spec:
+        raise ValueError(
+            f"Invalid handler format '{handler_spec}'. "
+            "Use path/to/file.py::function_name"
+        )
+
+    file_path, func_name = handler_spec.rsplit("::", 1)
+    path = Path(file_path)
+
+    if not path.exists():
+        raise FileNotFoundError(file_path)
+
+    spec = importlib.util.spec_from_file_location("_lambdaforge_handler", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    return getattr(module, func_name)
+
+
+def invoke_handler(
+    handler: Callable, event: dict
+) -> tuple[Any, str, float]:
+    """Invoke handler(event, context), capturing stdout and logging output.
+
+    Returns (return_value, captured_logs, duration_ms).
+    Exceptions from the handler propagate to the caller unchanged.
+    """
+    context = LambdaContext()
+    captured = io.StringIO()
+
+    log_handler = logging.StreamHandler(captured)
+    log_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+    root_logger = logging.getLogger()
+    root_logger.addHandler(log_handler)
+
+    start = time.perf_counter()
+    try:
+        with redirect_stdout(captured):
+            result = handler(event, context)
+    finally:
+        root_logger.removeHandler(log_handler)
+
+    duration_ms = (time.perf_counter() - start) * 1000
+    logs = captured.getvalue()
+
+    return result, logs, duration_ms

lambdaforge/mocking.py

@@ -0,0 +1,16 @@
+from contextlib import contextmanager
+from moto import mock_aws
+
+SUPPORTED_SERVICES: set[str] = {"dynamodb", "s3", "ssm", "sqs", "sns"}
+
+
+@contextmanager
+def activated_mocks(services: list[str]):
+    """Activate moto mock_aws() context manager.
+
+    All boto3 calls are intercepted regardless of which services are listed.
+    The services list is used for display/validation only — mock_aws() intercepts
+    everything uniformly. Mocked state is empty at start; see v1 limitation docs.
+    """
+    with mock_aws():
+        yield

lambdaforge/output.py

@@ -0,0 +1,42 @@
+import json
+
+from rich.console import Console
+from rich.syntax import Syntax
+
+console = Console()
+
+
+def print_header(handler_spec: str, event_path: str, services: list[str]) -> None:
+    console.print(f"[green]✓[/green] Handler: {handler_spec}")
+    console.print(f"[green]✓[/green] Event:   {event_path}")
+    if services:
+        console.print(f"[green]✓[/green] Mocks:   {', '.join(services)}")
+    console.print()
+
+
+def print_logs(logs: str) -> None:
+    if not logs.strip():
+        return
+    console.rule("Logs")
+    console.print(logs.rstrip())
+    console.print()
+
+
+def print_result(result: object) -> None:
+    console.rule("Return value")
+    try:
+        formatted = json.dumps(result, indent=2)
+        console.print(Syntax(formatted, "json", theme="monokai"))
+    except (TypeError, ValueError):
+        console.print(str(result))
+    console.print()
+
+
+def print_duration(duration_ms: float) -> None:
+    console.rule()
+    console.print(f"Duration: {duration_ms:.0f}ms")
+
+
+def print_error() -> None:
+    console.rule("[red]Error[/red]")
+    console.print_exception(show_locals=False)

lambdaforge_local-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: lambdaforge-local
+Version: 0.1.0
+Summary: Local AWS Lambda testing: generate realistic trigger events and invoke handlers with mocked AWS services
+Project-URL: Homepage, https://github.com/TretiqHiks/lambdaforge
+Project-URL: Source, https://github.com/TretiqHiks/lambdaforge
+Author: TretiqHiks
+License: MIT
+Keywords: aws,cli,lambda,local,moto,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: boto3>=1.26
+Requires-Dist: click>=8.0
+Requires-Dist: moto[all]>=4.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lambdaforge
+
+> Local AWS Lambda testing made simple.
+
+Generate realistic trigger event payloads and invoke your Python Lambda handler locally — with optional in-memory AWS service mocking via [moto](https://docs.getmoto.org/). No Docker. No SAM. No LocalStack.
+
+## Install
+
+```bash
+pip install lambdaforge
+```
+
+## Quick Start
+
+```bash
+# 1. Generate a realistic event file for your trigger type
+lambdaforge generate --trigger apigateway
+
+# 2. Edit event.json with your actual path, body, etc.
+
+# 3. Invoke your handler
+lambdaforge invoke --handler src/handler.py::lambda_handler
+
+# With mocked DynamoDB and S3 (boto3 calls intercepted, no real AWS)
+lambdaforge invoke --handler src/handler.py::lambda_handler --mock dynamodb,s3
+```
+
+## Supported Triggers
+
+| Trigger | CLI value |
+|---|---|
+| API Gateway REST proxy | `apigateway` |
+| SQS | `sqs` |
+| S3 object created | `s3` |
+| SNS | `sns` |
+| EventBridge / scheduled | `eventbridge` |
+
+## Supported Mock Services
+
+Pass any combination via `--mock`: `dynamodb`, `s3`, `ssm`, `sqs`, `sns`
+
+> **Note:** Mocked services start empty. Pre-populate state in your handler behind an env var guard if needed. Seed file support is planned for v2.
+
+## How It Works
+
+**`generate`** writes a complete AWS event JSON to a file (default: `event.json`). User-supplied fields are marked with `"<placeholder>"` strings.
+
+**`invoke`** loads your handler via Python's import system, builds a mock `LambdaContext`, optionally activates moto's `mock_aws()` context, and calls `handler(event, context)`. Output is formatted with [rich](https://github.com/Textualize/rich).
+
+## License
+
+MIT

lambdaforge_local-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+lambdaforge/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+lambdaforge/cli.py,sha256=9KDt9eBl8YyAtq8VySx9VYfAKvknAePTNbzHcY4E93Y,3331
+lambdaforge/invoker.py,sha256=SATvVl1V6WuuYWSjPg3D4-7F4SWc8NHvic1jV_xeJcc,2426
+lambdaforge/mocking.py,sha256=QsTGWiAsOC-XW_0_fZsNat_jOmR8v6e89Jc3v-PQrOw,532
+lambdaforge/output.py,sha256=9yplJWl0nuwH2Ng5DGK5TvWm_-rJGc_73oKHskU9MRc,1105
+lambdaforge/events/__init__.py,sha256=JyAW7pYsZGVcieYsHXszWJlVY7HsbM1vw1yJAXZXzck,244
+lambdaforge/events/apigateway.py,sha256=Mu9lDp5j0BUlot0zlmYsBBPZGjTdWxVX1gt_NkKU7eI,446
+lambdaforge/events/eventbridge.py,sha256=w-HbyjlHcMIuB1OUhY1jvmsvOZvYR9K4YSfxxWr69Bk,338
+lambdaforge/events/s3.py,sha256=npygoO24yjtS_W1Ae2ooXOxvlV3IhWC42a3vOy2IbFk,834
+lambdaforge/events/sns.py,sha256=KnBy1KVP14piK2JF74t7G7yAd_z8398m8P7EgXu_kOE,923
+lambdaforge/events/sqs.py,sha256=j4ZH2jv-6PKduEzo5yKSn1bc0vtAMBeDASYuScOEN3k,791
+lambdaforge_local-0.1.0.dist-info/METADATA,sha256=GbOACFeXaoneABIcfGB-5SxKjEnp2nSTjfsdSS3V5qs,2679
+lambdaforge_local-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+lambdaforge_local-0.1.0.dist-info/entry_points.txt,sha256=QJz2Gkh7GMnqAxgchX9iz2e5CzazNzRsTd88mtUjHhc,52
+lambdaforge_local-0.1.0.dist-info/RECORD,,

lambdaforge_local-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lambdaforge_local-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lambdaforge = lambdaforge.cli:cli