docs(data-classes): Add more cognito code examples

[michaelbrewer]

Issue #, if available:

Description of changes:

Changes:

• Add property raw_event to access the _data dict
• Add more code examples for Cognito triggers showing how to set response values.

eg:

from aws_lambda_powertools.utilities.data_classes.cognito_user_pool_event import (
   DefineAuthChallengeTriggerEvent
)

def handler(event: dict, context) -> dict:
   event: DefineAuthChallengeTriggerEvent = DefineAuthChallengeTriggerEvent(event)
   if (
       len(event.request.session) == 1
       and event.request.session[0].challenge_name == "SRP_A"
   ):
       event.response.issue_tokens = False
       event.response.fail_authentication = False
       event.response.challenge_name = "PASSWORD_VERIFIER"
   elif (
       len(event.request.session) == 2
       and event.request.session[1].challenge_name == "PASSWORD_VERIFIER"
       and event.request.session[1].challenge_result
   ):
       event.response.issue_tokens = False
       event.response.fail_authentication = False
       event.response.challenge_name = "CUSTOM_CHALLENGE"
   elif (
       len(event.request.session) == 3
       and event.request.session[2].challenge_name == "CUSTOM_CHALLENGE"
       and event.request.session[2].challenge_result
   ):
       event.response.issue_tokens = True
       event.response.fail_authentication = False
   else:
       event.response.issue_tokens = False
       event.response.fail_authentication = True

   return event.raw_event

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

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

[michaelbrewer]

@heitorlessa i expanded on the code examples for Cognito triggers to include how to set response values

[heitorlessa]

Thanks again @michaelbrewer for this contribution, much appreciated!

Made comments on areas that could have an additional explanation to ease reading, and some ideas for class methods to ease some Cognito challenges.

[codecov-io]

Codecov Report

Merging #340 (f01f0b4) into develop (542eb5b) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff            @@
##           develop     #340   +/-   ##
========================================
  Coverage    99.88%   99.88%           
========================================
  Files           95       95           
  Lines         3526     3529    +3     
  Branches       173      173           
========================================
+ Hits          3522     3525    +3     
  Misses           2        2           
  Partials         2        2           

Impacted Files	Coverage Δ
...lambda_powertools/utilities/data_classes/common.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 542eb5b...f01f0b4. Read the comment docs.

[heitorlessa]

Thanks a lot for the changes :) merging it!