Example api code updates (#3)

This adds some more complete code examples and usage of various pants
goals

Author: TonySherman

3rdparty/python/default.lock

@@ -1,4 +1,13 @@
+python_requirement(
+    name="jmespath",
+    requirements=["jmespath"],
+)
+
 python_requirements(
     name="root",
     source="pyproject.toml",
+    overrides={
+        "aws-lambda-powertools": {"dependencies": [":jmespath"]},
+    },
 )
+

BUILD

@@ -22,5 +22,31 @@ Pants commands are called _goals_. You can get a list of goals with
 pants help goals
 ```
 
+## Example Goals
+The following goals are configured in this repo.
+
+Run Formatter and linters:
+```
+pants lint fmt ::
+pants --changed-since=HEAD lint fmt :: # Only run on changed files
+```
+
+Run formatter and linters with fixes:
+```
+pants fix ::
+pants --changed-since=HEAD fix :: # Only run on changed files
+```
+
+Run Tests
+```
+pants test ::
+pants --changed-since=HEAD test :: # Only run on changed files
+```
+
+Package AWS Lambda Zip files
+```
+pants package ::
+```
+
 Most goals take arguments to run on. To run on a single directory, use the directory name with `:`
 at the end. To recursively run on a directory and all its subdirectories, add `::` to the end.

README.md

@@ -0,0 +1,3 @@
+python_test_utils(
+    name="test_utils",
+)

aws/BUILD

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+import pytest
+
+
+@pytest.fixture
+def lambda_context():
+	@dataclass
+	class LambdaContext:
+		function_name: str = 'test'
+		memory_limit_in_mb: int = 128
+		invoked_function_arn: str = 'arn:aws:lambda:eu-west-1:809313241:function:test'
+		aws_request_id: str = '52fdfc07-2182-154f-163f-5f0f9a621d72'
+
+	return LambdaContext()

aws/conftest.py

@@ -0,0 +1,23 @@
+# Example REST API on AWS
+
+This is a simplified example of a REST API that can be run on AWS using:
+
+ - [API Gateway](https://aws.amazon.com/api-gateway/)
+ - [AWS Lambda](https://aws.amazon.com/lambda/)
+
+This example includes the following lambda functions:
+
+    - A Get Item Lambda Function:
+        Used solely for retrieving items
+
+    - A Manage Items Lambda Function:
+        This lambda handles the rest of the CRUD operations, creating, updating, and deleting items.
+
+Pants allows a lot of flexibility with Lambda Functions. You can use single purpose lambda functions, such as the
+get_item function, or a lambda that serves several purposes.
+
+Pants will package both internal and external dependencies across your repo. Keep in mind AWS Lambda [Quotas](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) for package sizes.
+
+
+
+> **_Note:_** This very simplified example uses hard coded examples. We are just storing items in memory. This would likely be a database call in a production app.

aws/example_rest_api/README.md

@@ -1 +1,14 @@
 python_sources()
+
+python_aws_lambda_function(
+    name="get_item_lambda",
+    runtime="python3.11",
+    handler="get_item.py:lambda_handler",
+)
+
+
+python_aws_lambda_function(
+    name="manage_items_lambda",
+    runtime="python3.11",
+    handler="manage_items.py:lambda_handler",
+)

aws/example_rest_api/api/BUILD

@@ -0,0 +1,26 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response
+
+from aws.example_rest_api.models.item import Item
+
+app = ApiGatewayResolver()
+logger = Logger()
+
+items: dict[int, Item] = {
+	1: Item(item_id=1, name='test_item', description='test item description'),
+}
+
+
+@app.get('/items/<item_id>')
+def get_item(item_id: str):
+	item = items.get(int(item_id))
+
+	if item:
+		return Response(status_code=200, body=item.model_dump())
+
+	return Response(status_code=404)
+
+
+@logger.inject_lambda_context
+def lambda_handler(event, context):
+	return app.resolve(event, context)

aws/example_rest_api/api/create_user.py

@@ -0,0 +1,55 @@
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response
+
+from aws.example_rest_api.models.item import Item
+
+app = ApiGatewayResolver(enable_validation=True)
+logger = Logger()
+
+
+items: dict[int, Item] = {
+	1: Item(item_id=1, name='test_item', description='test item description'),
+}
+
+
+@app.delete('/items/<item_id>')
+def delete_item(item_id: str):
+	item = items.get(int(item_id))
+	if item:
+		logger.info(f'Removing Item: {item.name}')
+		del items[item.item_id]
+
+		return Response(status_code=204)
+
+	logger.info('Unable to process request, Item not found')
+	return Response(status_code=400)
+
+
+@app.post('/items')
+def create_item(request_body: Item):
+	if request_body.item_id in items:
+		logger.info('Item already exists, unable to create')
+		return Response(status_code=400)
+
+	items[request_body.item_id] = Item(**request_body.model_dump())
+
+	return Response(
+		status_code=201,
+		headers={'Location': f'https://example.com/items/{request_body.item_id}'},
+	)
+
+
+@app.patch('/items/<item_id>')
+def update_item_details(item_id: str, item_update: Item):
+	item = items.get(int(item_id))
+	if item:
+		logger.info(f'Updating {item.name}', update_request=item_update.model_dump())
+		items[item_update.item_id] = item_update
+		return Response(status_code=200)
+
+	logger.error('unable to find existing item')
+	return Response(status_code=404)
+
+
+def lambda_handler(event, context):
+	return app.resolve(event, context)

aws/example_rest_api/api/get_item.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+	item_id: int
+	name: str
+	description: str

aws/example_rest_api/api/get_user.py

@@ -0,0 +1 @@
+python_tests()

aws/example_rest_api/api/manage_items.py

@@ -0,0 +1,20 @@
+from aws.example_rest_api.api.get_item import lambda_handler
+
+
+def test_retrieve_item_from_lambda_handler(lambda_context):
+	payload = {
+		'version': '1.0',
+		'resource': '/items/{item_id}',
+		'path': '/items/1',
+		'httpMethod': 'GET',
+		'pathParameters': {'item_id': '1'},
+	}
+
+	response = lambda_handler(payload, lambda_context)
+
+	assert response['body'] == {
+		'item_id': 1,
+		'name': 'test_item',
+		'description': 'test item description',
+	}
+	assert response['statusCode'] == 200

aws/example_rest_api/api/update_user.py

@@ -0,0 +1,57 @@
+from unittest.mock import patch
+
+from aws.example_rest_api.api.manage_items import lambda_handler
+from aws.example_rest_api.models.item import Item
+
+
+@patch(
+	'aws.example_rest_api.api.manage_items.items',
+	{2: Item(item_id=2, name='delete_me', description='delete_me')},
+)
+def test_delete_item(lambda_context):
+	payload = {
+		'version': '1.0',
+		'resource': '/items/{item_id}',
+		'path': '/items/2',
+		'httpMethod': 'DELETE',
+		'pathParameters': {'item_id': '2'},
+	}
+	response = lambda_handler(payload, lambda_context)
+
+	assert response['statusCode'] == 204
+
+
+def test_create_item(lambda_context):
+	payload_body = Item(item_id=3, name='new_item', description='new item').model_dump_json()
+	payload = {
+		'version': '1.0',
+		'path': '/items',
+		'httpMethod': 'POST',
+		'body': payload_body,
+		'resource': '/items',
+	}
+
+	response = lambda_handler(payload, lambda_context)
+
+	assert response['statusCode'] == 201
+
+
+@patch(
+	'aws.example_rest_api.api.manage_items.items',
+	{9: Item(item_id=9, name='change_me', description='change_me')},
+)
+def test_update_item(lambda_context):
+	payload_body = Item(
+		item_id=9, name='changed_item', description='changed item'
+	).model_dump_json()
+	payload = {
+		'version': '1.0',
+		'path': '/items/9',
+		'httpMethod': 'PATCH',
+		'body': payload_body,
+		'resource': '/items/9',
+	}
+
+	response = lambda_handler(payload, lambda_context)
+
+	assert response

aws/example_rest_api/models/item.py

@@ -3,10 +3,12 @@ pants_version = "2.20.0"
 
 backend_packages = [
   "pants.backend.python",
-  "pants.backend.python.lint.black",
   "pants.backend.awslambda.python",
+  "pants.backend.experimental.python.lint.ruff.check",
+  "pants.backend.experimental.python.lint.ruff.format",
 ]
 
 [python]
 enable_resolves=true
 interpreter_constraints = ["CPython==3.11.*"]
+

aws/example_rest_api/models/user.py

@@ -1,4 +1,32 @@
 [project]
+name = "pants_example_serverless"
 dependencies = [
-    "aws-lambda-powertools[all]",
+    "aws-lambda-powertools",
+    "pydantic",
 ]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+]
+test = [
+    "pytest",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # isort
+    "I",
+]
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "tab"
+docstring-code-format = true