docs: new parser utility

[heitorlessa]

Issue #, if available: #118

Description of changes:

Documentation for upcoming advanced parser.

Rendered doc: https://github.com/heitorlessa/aws-lambda-powertools-python/blob/docs/parser/docs/content/utilities/parser.mdx

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics
• Document key features
• Document how to install additional dependencies (pydantic, typing_extension)
• Document event_parser decorator
• Document parse standalone function
• Document models vs envelopes terminology
• Document built-in envelopes
• Document inheriting models to access all their properties e.g. EventBridgeModel
• Document how to use root_validator and validator
• Document exception handling
• Document cold start impact
• Review by Ran (utility author)
• If possible, get a review by Koudai
• revert: Use Pydantic's ValidationError as opposed to ours given its utility functions json(), errors(), etc. Original implementation also provided a better experience for those migrating existing Pydantic models and validations, which I can only see why not.

Breaking change checklist

RFC issue #:

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

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

[codecov-io]

Codecov Report

Merging #192 into develop will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff            @@
##           develop     #192   +/-   ##
========================================
  Coverage    99.87%   99.87%           
========================================
  Files           65       66    +1     
  Lines         2451     2457    +6     
  Branches       108      107    -1     
========================================
+ Hits          2448     2454    +6     
  Misses           3        3           

Impacted Files	Coverage Δ
...s_lambda_powertools/utilities/parser/exceptions.py	100.00% <ø> (ø)
aws_lambda_powertools/utilities/parser/__init__.py	100.00% <100.00%> (ø)
..._powertools/utilities/parser/envelopes/__init__.py	100.00% <100.00%> (ø)
...mbda_powertools/utilities/parser/envelopes/base.py	100.00% <100.00%> (ø)
..._powertools/utilities/parser/envelopes/dynamodb.py	100.00% <100.00%> (ø)
...ertools/utilities/parser/envelopes/event_bridge.py	100.00% <100.00%> (ø)
...ambda_powertools/utilities/parser/envelopes/sqs.py	100.00% <100.00%> (ø)
aws_lambda_powertools/utilities/parser/parser.py	100.00% <100.00%> (ø)
aws_lambda_powertools/utilities/parser/types.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 6a5889b...3750d55. Read the comment docs.

[heitorlessa]

hey @risenberg-cyberark @koxudaxi - Would appreciate if you could review the new parser's docs before we release it.

Parser is a thin wrapper on top of Pydantic

[koxudaxi]

@heitorlessa
Thank you for requesting a review.
I wrote some comments.
I think TypeVar can support that users decide types of models.
I guess _parse and parse methods should have TypeVar arguments for Models.

[heitorlessa]

@heitorlessa

Thank you for requesting a review.

I wrote some comments.

I think TypeVar can support that users decide types of models.

I guess _parse and parse methods should have TypeVar arguments for Models.

All great comments; I'll reply to them but first a question @koxudaxi:

What's the value in using parser with "str" as a model?

If nothing will be parsed, why not use the data class utility we provide?

We had support for str in the original implementation by Ran but I struggled to see the value if you know the value will be just a str - I might me missing something hence the question

Thanks a lot everyone

[heitorlessa]

All addressed @koxudaxi and I've just learned we don't need the additional Type[Model], Model does it just fine according to PyCharm Code inspection feature.

[koxudaxi]

All addressed @koxudaxi and I've just learned we don't need the additional Type[Model], Model does it just fine according to PyCharm Code inspection feature.

@heitorlessa
By the way, I'm developing a PyCharm plugin of Pydantic. https://github.com/koxudaxi/pydantic-pycharm-plugin
About the plugin is written in an official pydantic document too:smile_cat:

[heitorlessa]

Thanks a lot @risenberg-cyberark and @koxudaxi for the review - I'm merging this now with all feedbacks being addressed, and will work on the 1.7.0 release tomorrow by EOD to include this publicly ;)