Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(parser): change parser documentation #5262

Open
wants to merge 7 commits into
base: develop
Choose a base branch
from
Open

docs(parser): change parser documentation #5262

wants to merge 7 commits into from

Conversation

anafalcao
Copy link
Collaborator

@anafalcao anafalcao commented Sep 27, 2024 •
edited
Loading

Issue number: #1371

Summary

This PR refreshes Parser docs with newer features like examples, improves wording and navigation, focused on Powertools v3.

Changes

  • Clean up the initial explanation
  • Clean up Key Features
  • Move the info "this is not necessary if using Layers" to the top
  • Remove Pydantic 1 integration
  • Add a QuickStart with BaseModels and Parse events
  • Add sections Getting Started and Advanced
  • Fix the parse() function example and initial explanation
  • Add differences between of parse() and event_parser
  • Clean up the example of extending built-in models; add pre and post explanations
  • Clean up the Envelopes example and improve the initial explanation
  • Complete the Validating fields example
  • Clean up the root_validator example
  • Move the Pydantic helper functions box to Getting started section
  • Restructure Serialization; add a functional example
  • Clean up the two examples of string fields that contain JSON data
  • Clean up the Bringing your own envelope examples

User experience

Please share what the user experience looks like before and after this change

modifcations_for_new_parser

Checklist

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

Is this a breaking change?

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 boring-cyborg bot added the documentation Improvements or additions to documentation label Sep 27, 2024
@pull-request-size pull-request-size bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Sep 27, 2024
@boring-cyborg boring-cyborg
Copy link

boring-cyborg bot commented Sep 27, 2024

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

@anafalcao anafalcao changed the title docs(parser): change parser documentation - WIP docs(parser): change parser documentation Sep 27, 2024
@anafalcao anafalcao changed the title docs(parser): change parser documentation docs(parser): change parser documentation - WIP Sep 27, 2024
@anafalcao anafalcao marked this pull request as ready for review September 27, 2024 17:56
@anafalcao anafalcao requested a review from a team as a code owner September 27, 2024 17:56
@leandrodamascena leandrodamascena marked this pull request as draft October 7, 2024 10:41
@leandrodamascena leandrodamascena mentioned this pull request Oct 9, 2024
Closed
@dreamorosi dreamorosi mentioned this pull request Oct 14, 2024
Open
@leandrodamascena leandrodamascena mentioned this pull request Oct 17, 2024
Open
@pull-request-size pull-request-size bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Oct 17, 2024
@github-actions GitHub Actions
Copy link
Contributor

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

@sonarcloud SonarCloud
Copy link

sonarcloud bot commented Oct 21, 2024

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

@anafalcao anafalcao marked this pull request as ready for review October 21, 2024 12:12
@anafalcao
Copy link
Collaborator Author

Hey @leandrodamascena !
Can you please review this PR? Something is missing for this issue #5390, and I may need some direction to fix it.
Thanks

@leandrodamascena leandrodamascena changed the title docs(parser): change parser documentation - WIP docs(parser): change parser documentation Oct 21, 2024
leandrodamascena
leandrodamascena requested changes Oct 21, 2024
View reviewed changes
Copy link
Contributor

@leandrodamascena leandrodamascena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @anafalcao! This is amazing to start reviewing this PR, indeed a great improvement in our documentation.

I see we have room to improve some areas and I left some comments. Can you please review and address them before we move to the next round of this review?

docs/utilities/parser.md
handler(event=payload, context=LambdaContext())
handler(event=json.dumps(payload), context=LambdaContext()) # also works if event is a JSON string
```
#### Parse function
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @anafalcao, there is something weird here. Pls take a look

image

docs/utilities/parser.md
Comment on lines +50 to +52
```python title="getting_started_with_parser.py"
--8<-- "examples/parser/src/getting_started_with_parser.py"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights here.

docs/utilities/parser.md
Comment on lines +160 to +162
```python
--8<-- "examples/parser/src/envelope_with_event_parser.py"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
Comment on lines +166 to +168
```json
--8<-- "examples/parser/src/envelope_payload.json"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
resources: List[str]
detail_type: str = Field(None, alias="detail-type")
detail: Dict[str, Any]
--8<-- "examples/parser/src/bring_your_own_envelope.py"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
parsed_envelope = EventBridgeModel.model_validate(data)
return self._parse(data=parsed_envelope.detail, model=model)
```json
--8<-- "examples/parser/src/bring_your_own_envelope.json"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
Comment on lines +238 to +239
```python title="field_validator.py"
--8<-- "examples/parser/src/field_validator.py"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
Comment on lines +250 to +252
```python title="field_validator_all_values.py"
--8<-- "examples/parser/src/field_validator_all_values.py"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
Comment on lines +267 to +268
```python title="model_validator.py"
--8<-- "examples/parser/src/model_validator.py"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

docs/utilities/parser.md
Comment on lines +283 to +285
```python
--8<-- "examples/parser/src/string_fields_contain_json.py"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing highlights.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@leandrodamascena leandrodamascena leandrodamascena requested changes

Requested changes must be addressed to merge this pull request.

Assignees

@anafalcao anafalcao

Labels
documentation Improvements or additions to documentation size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@anafalcao @leandrodamascena