Implement the Todo List API

Added the Todo List API along with all required components including endpoints, models, services, exception handlers and tests. This commit includes integration with a database and AWS services. The majority of the implementation is located in the newly added 'tasks' directory. Various functionalities such as create a task, delete a task, get task by ID, list tasks, and update task are supported. Further improvements and additional features will be added as necessary.

.env.example

@@ -0,0 +1,9 @@
+# AWS
+AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID>
+AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY>
+AWS_DEFAULT_REGION=us-east-1
+
+# Dev
+DB_HOST=http://dynamodb:8000
+DB_TASKS_TABLE=todo-list-tasks
+DEBUG=true

.github/workflows/test.yaml

@@ -0,0 +1,12 @@
+name: Test
+on:
+  push:
+    branches:
+      - main
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run type checking, linting, and unit tests.
+        run: make ci-test

.gitignore

@@ -0,0 +1,215 @@
+# Created by https://www.toptal.com/developers/gitignore/api/macos,python
+# Edit at https://www.toptal.com/developers/gitignore?templates=macos,python
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/macos,python
+
+# IDE
+.idea
+
+# Dev
+dist

Makefile

@@ -0,0 +1,98 @@
+project_name:=todo-list
+cfn_dir:=stack/cfn
+dist_dir:=dist
+
+# parameters
+api_debug:=true
+
+# Docker
+.PHONY: up
+up: create-dev-env
+	@docker compose up --build -d
+
+.PHONY: down
+down:
+	@docker compose down -v
+
+.PHONY: create-dev-env
+create-dev-env:
+	@test -e .env || cp .env.example .env
+
+# CI/CD
+.PHONY: ci-%
+ci-%: create-dev-env
+	@docker compose run --rm dev sh -c 'make $*'
+
+.PHONY: deploy
+deploy:
+	@rain deploy -y $(cfn_dir)/api.yaml $(project_name) --params Debug=$(api_debug)
+
+# Dev
+.PHONY: test
+test: lint-actions test-cfn test-py
+
+.PHONY: build
+build: cleanup-build build-py
+
+.PHONY: cleanup-build
+cleanup-build:
+	@rm -rf ${dist_dir}
+	@mkdir -p ${dist_dir}
+
+## CFN
+.PHONY: test-cfn
+test-cfn: format-cfn lint-cfn
+
+.PHONY: format-cfn
+format-cfn:
+	@rain fmt $(cfn_dir)/*.yaml -w
+
+.PHONY: lint-cfn
+lint-cfn:
+	@cfn-lint $(cfn_dir)/**/*.yaml
+
+## Lambda
+.PHONY: build-py
+build-py:
+	@# https://github.com/python-poetry/poetry/issues/1937
+	@poetry build -f wheel -o ${dist_dir}/wheel
+	@pip install ${dist_dir}/wheel/*.whl -t ${dist_dir}/app
+
+.PHONY: test-py
+test-py: full-install type-py lint-py unit-py
+
+.PHONY: lint-py
+lint-py:
+	@# run both ruff format and lint. https://github.com/astral-sh/ruff/issues/8232
+	@poetry run ruff format .
+	@poetry run ruff check .
+
+.PHONY: type-py
+type-py:
+	@poetry run mypy .
+
+.PHONY: unit-py
+unit-py:
+	@poetry run pytest
+
+.PHONY: full-install
+full-install:
+	@poetry install
+
+## Action
+lint-actions:
+	@actionlint
+
+## Local
+.PHONY: server
+server: create-table
+	@cd src && uvicorn app.main:app --reload --host 0.0.0.0 --port 8080
+
+.PHONY: create-table
+create-table:
+	@mkdir -p ${dist_dir}/dynamodb
+	@aws dynamodb create-table --table-name ${DB_TASKS_TABLE} \
+		--attribute-definitions AttributeName=id,AttributeType=S \
+		--key-schema AttributeName=id,KeyType=HASH \
+		--provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5 \
+		--endpoint-url ${DB_HOST} > /dev/null  2>&1 || echo "Table already exists. Skipping creation."

README.md

@@ -0,0 +1,58 @@
+# Python API Starter
+
+[![Test](https://github.com/CameronXie/python-api-starter/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/CameronXie/python-api-starter/actions/workflows/test.yaml)
+
+This project aims to serve as a practical example of how to build a RESTful API in Python by showcasing a To-Do List API
+tool.
+
+## Folder Structure
+
+```shell
+.
+├── Makefile
+├── README.md
+├── docker
+│   └── dev
+├── docker-compose.yaml
+├── docs
+│   └── openapi_docs.png
+├── poetry.lock
+├── pyproject.toml
+├── src
+│   └── app
+│       ├── __init__.py
+│       ├── api.py
+│       ├── config.py
+│       ├── exception_handlers.py
+│       ├── main.py                  # Entry point to API
+│       └── tasks                    # Task related resources
+├── stack
+│   └── cfn
+│       └── api.yaml                 # IaC Cloudformation template
+└── tests
+    ├── __init__.py
+    └── app                          # Unit tests
+```
+
+## Development
+
+This project is built with Docker to handle the local development environment smoothly. To initiate the development
+container, execute the command `make up`.
+
+Inside the `python_api_dev` container, run `poetry install` for installing all the necessary dependencies. After
+completion, type `make server` to launch the Todo list API within the container. Following this, you can access the API
+via your web browser at https://localhost:8080/v1. Additionally, the OpenAPI documentation for the API can be accessed
+at https://localhost:8080/v1/docs.
+
+![OpenAPI](docs/openapi_docs.png)
+
+## Deployment
+
+The solution leverages the capabilities of AWS API Gateway and AWS Lambda services. To deploy the Todo List API to AWS,
+simply run the `make deploy` command.
+
+## Test
+
+To test the lambda source code, cloudformation template and Github actions file, use the `make test` command. This
+performs type checking, linting, and unit tests. Ensure to resolve any highlighted issues before proceeding to
+deployment.