Metadata-Version: 2.4
Name: kegstandcli
Version: 0.3.10
Summary: The Developer's Toolbelt For Accelerating Mean-Time-To-Party on AWS
Project-URL: Homepage, https://kegstand.dev
Project-URL: Repository, https://github.com/jensroland/kegstand
Author-email: JensRoland <mail@jensroland.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aws-cdk-lib>=2.67.0
Requires-Dist: aws-solutions-constructs-aws-apigateway-lambda>=2.39.0
Requires-Dist: boto3>=1.17.113
Requires-Dist: click>=8.0.3
Requires-Dist: constructs<11.0.0,>=10.0.0
Requires-Dist: copier>=9.4.1
Requires-Dist: directory-tree>=1.0.0
Requires-Dist: pyjwt>=2.1.0
Requires-Dist: tomlkit>=0.11.7
Requires-Dist: xxhash>=3.2.0
Description-Content-Type: text/markdown

<!-- markdownlint-disable first-line-h1 line-length no-inline-html -->
<p align="center">
  <a href="https://kegstand.dev/">
    <img src="https://kegstand.dev/assets/kegstand-logotype.png" width="540px" alt="Kegstand logo" />
  </a>
</p>

<h3 align="center">The Developer's Toolbelt For Accelerating <em>Mean Time To Party</em> on AWS</h3>
<p align="center">Created by <a href="https://jensroland.com/">Jens Roland</a> and fueled by a non-zero amount of alcohol</p>
<p align="center"><a href="https://kegstand.dev/demo">Watch a 3-minute demo</a></p><!-- markdown-link-check-disable-line -->

<br />

## 🥂💃🕺 Welcome to the Party! 🥂💃🕺

Kegstand is a free and open-source framework for creating Python APIs and services. It allows you to rapidly build and deploy services on AWS. We all have better things to do than `print(json.dumps(event))` all day long, and Kegstand is here to help you get to the party &mdash; _and into Prod_ &mdash; a lot faster.

**It provides:**

- A CLI tool for creating and deploying your services.
- A decorator based API abstracting away the boilerplate of Lambda, API Gateway, Cognito, and more.
- The full power of CDK to define and deploy arbitrary AWS resources with your services.

> _"Experience a streamlined cloud development process, enhanced productivity, and hit that "party" button sooner with Kegstand!"_ > **&mdash; GPT-4, official spokesbot for the Kegstand team**

Learn more on the [Kegstand website](https://kegstand.dev/).

## Prerequisites

- [Python 3.12+](https://www.python.org/downloads/)
- [uv](https://github.com/astral-sh/uv) or [Poetry](https://python-poetry.org/docs/#installation)
- An [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/)
- The AWS CLI [configured with credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)
- The [CDK CLI configured on the local machine and initialized on the AWS account](https://docs.aws.amazon.com/cdk/latest/guide/getting_started.html)
- A well-poured [Belgian style brown ale](https://www.grimbergen.com/)

## Quick start

To create a service with Kegstand, you'll need a Python project with a few dependencies and a folder structure following the Kegstand convention.

You can create this in a few seconds, either with the Kegstand CLI or using [Copier](https://copier.readthedocs.io/en/stable/#installation).

```shell
# Using the Kegstand CLI
> uvx install kegstandcli  # Or `pipx install kegstandcli`
> keg new my-service

# Using Copier
> copier copy -d project_name=my-service gh:JensRoland/kegstand-project-template .
```

Either method will create a new project folder called `my-service` containing:

```shell
📁 my-service
├── 📄 .gitignore                    # Standard .gitignore file
├── 📄 pyproject.toml                # Project configuration
└── 📁 src
    └── 📁 api
        └── 📁 public
            └── 📄 hello.py          # Logic for /hello/
```

Kegstand projects are minimal by design, so a fresh project folder contains just those 3 files. Well, apart from a few empty `__init__.py` gatecrashers, but we can safely ignore those.

Install the dependencies for the new project (uv will do this for you during `uv run` so it's not strictly necessary):

```shell
> cd my-service
> uv sync
```

Finally, to build and deploy the service to AWS:

```shell
> uv run keg deploy
```

> **Note**: If you installed the Kegstand CLI globally with `uvx` or `pipx`, you could also run `keg deploy` directly, but it is recommended to use `uv run` to ensure that you are using the correct CLI version for the specific project.

You should now be able to access the API endpoint at `https://<api-id>.execute-api.<region>.amazonaws.com/prod/hello`.

## Documentation

For further examples and more advanced usage, see the [official documentation](https://github.com/JensRoland/kegstand/blob/main/docs/index.md).

## Roadmap

Here are some notable changes, fixes and features that are planned for development:

## 0.4.0

- [ ] More content on [kegstand.dev](https://kegstand.dev)
- [X] Custom domain names
- [X] Support multiple repos using the same domain (and API Gateway)
- [X] Simplify the folder structure from `src/api/resources/<resource-name>/<method>.py` to `src/api/<resource-name>.py`
- [X] Add support for [uv](https://docs.astral.sh/uv/) for package management in projects
- [X] Write unit tests

### Pre-1.0.0

- [ ] Increase test coverage to >70% and configure CI to enforce this for all PRs
- [ ] Specify event triggers for Lambda functions: S3, SNS, SQS, DynamoDB, Cloudwatch CRON scheduled events, etc.
- [ ] Pagination helper
- [ ] [Record a screencast](https://asciinema.org/) for the README
- [ ] Autogenerated docs using [MkDocs](https://www.mkdocs.org/) or similar
- [ ] GitHub Actions workflow for pushing docs to the website

### 1.0.0

- [ ] Intuitive and mostly automated API Versioning
- [ ] Simple way to define/override core API/Lambda properties such as CPU/MEM, Python runtime version, warm pool (!), and concurrency
- [ ] Deploy Lambda-only microservices with no API Gateway
- [ ] Folder of example projects for common use cases: CRUD, auth, File management on S3.

### Future

- [ ] Configurable log level
- [ ] Add AWS tags in the Kegstand config and they will be applied to the generated resources
- [ ] Easily add [AWS Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html)
- [ ] Add support for APIs using [FastAPI](https://fastapi.tiangolo.com/) with [Mangum](https://mangum.io/) instead of the default Kegstand API framework, and just provide deployment helpers for the API Gateway and Lambda
- [ ] Improved output from deploy command; friendly post-deploy instructions for testing your API
- [ ] Version bumper with [bump2version](https://pypi.org/project/bump2version/)
- [ ] Include more goodies from [Lambda Powertools](https://awslabs.github.io/aws-lambda-powertools-python/2.11.0/) - tracing, metrics, etc.
- [ ] Add support for APIs using pure [Lambda Powertools](https://awslabs.github.io/aws-lambda-powertools-python/2.11.0/) instead of the default Kegstand API framework, and just provide deployment helpers for the API Gateway and Lambda
- [ ] Unit testing helpers (wrap moto and make it all a little more DRY and intuitive)
- [ ] Secure endpoints which require re-authentication (and/or MFA) so a refreshed token isn't enough (to, say, delete your account or change your credit card info)
- [ ] Live Lambda development a la SST
- [ ] Build and deploy gRPC endpoints (or similar alternative)
- [ ] Option to teardown before deploying: `keg deploy --force-redeploy`
- [ ] Use env vars to populate values in kegstand.toml
- [ ] Add kegstand.toml schema to the [JSON Schema Store](https://www.schemastore.org/json/) and add the schema URL at the top like `#:schema https://json.schemastore.org/kegstand.json`
- [ ] Merge Kegstand and Beth into one tool?
- [ ] CDK Pipelines
- [ ] Support HTTP method-specific files (e.g. `get.py`, `post.py`, etc.)
- [X] Upgrade Copier once the [template-deleting bugfix](https://github.com/copier-org/copier/pull/1037) is released
