feat(event_handler): add decorator for HTTP HEAD verb

[nlykkei]

Issue number: #4264

Fixes#4263, fixes#4264

Summary

Add BaseRouter.head for supporting HEAD requests, which are common and associated to GET requests:

The HTTP HEAD method requests the headers that would be returned if the HEAD request's URL was instead requested with the HTTP GET method

Conversely, TRACE and CONNECT methods are less common, and should not have first-class support, but should instead be handled like @app.route("/todos", method=["TRACE", "CONNECT"])

Changes

Added BaseRouter.head for supporting HEAD requests and updated docs according to #4263 to clarity that other methods can be handled using @app.route.

User experience

Example:

fromaws_lambda_powertools.event_handlerimportAPIGatewayRestResolver, Response, content_typesapp=APIGatewayRestResolver()
@app.head("/head-call")defsimple_head():
returnResponse(status_code=200,
content_type=content_types.APPLICATION_JSON,
body="A",
headers={"Content-Length": "123"})
deflambda_handler(event, context):
returnapp.resolve(event, context)

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

No

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[nlykkei]

@rubenfonseca Hi Ruben :) I made a first PR with few changes. Could you say, whether it looks correct? 👍

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.16%. Comparing base (e14e768) to head (f73567e).
Report is 392 commits behind head on develop.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@ Coverage Diff @@## develop #4275 +/- ##
===========================================
- Coverage 96.38% 96.16% -0.22% 
===========================================
Files 214 218 +4 Lines 10030 10463 +433 Branches 1846 1936 +90 ===========================================
+ Hits 9667 10062 +395 - Misses 259 283 +24 - Partials 104 118 +14 

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
23.1% Duplication on New Code

See analysis details on SonarCloud

[leandrodamascena]

Hello @nlykkei! Firstly, what an extremely fast and high quality contribution!!

I'm OnCall this week and I'm responsible for reviewing PR's, issues and things like that! I have nothing to change in this PR and I will approve it!

Congratulations and I hope it can be the first of many! 🚀

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!