Metadata-Version: 2.1
Name: lambdaq
Version: 0.0.1
Summary: Helps you write Amazon Web Services Lambda functions called by Step Functions via SQS
Author: Cariad Eccleston
Author-email: cariad@cariad.earth
License: MIT
Project-URL: Project, https://github.com/cariad/lambdaq
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3 ~=1.0

# LambdaQ

**LambdaQ** ("lambda queue") is a Python package that helps you to write Amazon Web Services Lambda functions that receive events from Step Functions state machines via SQS queues.

## Why use it?

Frankly, I write a lot of Lambda functions that need to be invoked by Step Functions state machines via SQS queues, and my team is as bored reviewing the boilerplate as I am writing it.

I also find myself needing to upgrade Lambda functions from direct invocation to indirect via-SQS invocation for resilience, and I wanted a handler that supports both event styles during migrations.

So, LambdaQ helps you to write clean, testable Lambda functions without needing to care whether the event arrived directly or via a queue.

## Example

Say you want to build a Lambda function that sums two numbers together then returns the result. You want this function to be invoked by a Step Functions state machine, and you want the function to be deployed behind an SQS queue for resilience.

With LambdaQ, your script looks like this:

```python
from typing import Any, TypedDict
from lambdaq import handle_event

class Inputs(TypedDict):
    x: int
    y: int
    task_token: str

class Sum(TypedDict):
    result: int

def main(event: Any, context: Any) -> Sum | None:
    return handle_event(
        event,
        perform_sum,
        "task_token",
    )

def perform_sum(inputs: Inputs) -> Sum:
    return Sum(result=inputs["x"] + inputs["y"])
```

The `lambdaq.handle_event` function reads the invocation event, a reference to a message handler, and the key of the task token injected by the state machine.

The message handler--`perform_sum` in this example--reads a strongly-typed message and returns a strongly-typed response.

## How does it work?

Behind the scenes, LambdaQ checks if the event describes a single direct invocation or a collection of (one or more) messages plucked from an SQS queue.

If the event describes a single direct invocation, LambdaQ calls the message handler then returns the response directly.

if the event describes a collection of messages from a queue then LambdaQ calls the message handler for each message, and includes calls to the Step Functions `send_task_success`and `send_task_failure` APIs as-and-when each message succeeds or fails.

## Installation

LambdaQ requires Python 3.10 or later and can be installed from [PyPI](https://pypi.org/project/lambdaq/).

```shell
pip install lambdaq
```

## Support

Please submit all your questions, feature requests and bug reports at [github.com/cariad/lambdaq/issues](https://github.com/cariad/lambdaq/issues). Thank you!

## Licence

LambdaQ is [open-source](https://github.com/cariad/lambdaq) and released under the [MIT License](https://github.com/cariad/lambdaq/blob/main/LICENSE).

You don't have to give attribution in your project, but--as a freelance developer with rent to pay--I appreciate it!

## Author

Hello! 👋 I'm **Cariad Eccleston**, and I'm a freelance Amazon Web Services architect, DevOps evangelist, CI/CD pipeline engineer and backend developer.

You can find me at [cariad.earth](https://cariad.earth), [github.com/cariad](https://github.com/cariad), [linkedin.com/in/cariad](https://linkedin.com/in/cariad) and on the Fediverse at [@cariad@gamedev.lgbt](https://gamedev.lgbt/@cariad).
