docs: convert docstrings to Google style in parser_tools and component (#1072) - #1749

@AhmadBilalDSA AhmadBilalDSA commented Sep 1, 2026 •

edited

Loading

Copy link

Copy Markdown

Summary of changes

Converts legacy docstrings in src/icalendar/parser_tools.py and src/icalendar/cal/component.py to Google Python Style with Parameters: and Returns: sections per project documentation guidelines.

See #1072

Checklist

I have read the contributing guidelines.
I have added tests for my changes (or confirmed existing test suite passes).
The pull request targets the main branch.
I have updated the documentation where applicable.

AhmadBilalDSA requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners

September 1, 2026 20:34

@github-actions github-actions Bot added the ai-suspicion label

@github-actions

github-actions Bot commented Sep 1, 2026

Copy link

Copy Markdown

Contributor

This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments.

@github-actions

github-actions Bot commented Sep 1, 2026

Copy link

Copy Markdown

Contributor

Profile summary:

GitHub user: AhmadBilalDSA
🔴 Significant concerns found with user's profile.
🟡 Some concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.
For a more detailed report, run `gh-profiler AhmadBilalDSA`.

Full profile

GitHub user: AhmadBilalDSA
🔴 Significant concerns found with user's profile.
 🔴 Account age: a month
 🟢 Profile information:
 name: Ahmad Bilal
 location: Pakistan
 email: kierninja@gmail.com
 bio: Data Analyst & Analytics Specialist bridging business intelligence and data engineering. Focused on Python, SQL, DuckDB/Polars, and building automated data work
 linkedin: https://linkedin.com/in/AhmadBilalDES
 Empty fields: company, blog
🟡 Some concerns found with recent PR activity.
 40 PRs opened in the last 21 days.
 9 opened against repos the user owns.
 0 opened against repos in publicly associated orgs.
 31 opened against external repos.
 🟡 7 of 31 external PRs closed without merging in the last 21 days.
🟢 No concerns found with recent issue activity.
 5 new issues opened in the last 21 days.
 3 opened in repos the user owns.
 0 opened in repos in publicly associated orgs.
 2 opened in external repos.
 🟢 0 external issues closed as NOT_PLANNED.
 🟢 0 external issues opened with the same title.

@read-the-docs-community

read-the-docs-community Bot commented Sep 1, 2026 •

edited

Loading

Copy link

Copy Markdown

Documentation build overview

📚 icalendar | 🛠️ Build #34420906 | 📁 Comparing 863d389 against latest (acbee8c)

🔍 Preview build

32 files changed · ± 32 modified

± Modified

AhmadBilalDSA added a commit to AhmadBilalDSA/icalendar that referenced this pull request


 docs: add changelog entry for collective#1072 ( collective#1749 )

c4c5f86

AhmadBilalDSA commented Sep 1, 2026

Copy link

Copy Markdown

Author

Hi @stevepiercy @niccokunzmann,

I have added the changelog entry to resolve the changelog check.

Regarding the bot tag: this PR is strictly scoped to converting docstrings in parser_tools.py and cal/component.py to Google Python Style for #1072, with all tests passing locally via pytest.

Please let me know if you would like any adjustments to the wording or style.

AhmadBilalDSA added a commit to AhmadBilalDSA/icalendar that referenced this pull request


 chore: move news fragment to docs/changelog/1749.doc.rst ( collective#...

afe9b60

...1749)

AhmadBilalDSA added a commit to AhmadBilalDSA/icalendar that referenced this pull request


 docs: add towncrier news fragment at news/1072.documentation.rst ( col...

...lective#1749)

stevepiercy

stevepiercy requested changes

Sep 2, 2026

View reviewed changes

@stevepiercy stevepiercy left a comment

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

Please revert all section headings of Args back to Parameters. See Docstring structure and the note under Parameters for an explanation. Thank you!

angatha

angatha requested changes

Sep 2, 2026

View reviewed changes

@angatha angatha left a comment

Copy link

Copy Markdown

Collaborator

Choose a reason for hiding this comment

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

Just a small note: You wrote "Fixes #xxx". That would close the Issue once th PR is merged. Since the issue is (most likely) not done with this, use "See #xxx" instead. That will link the issue but does not close it.

@niccokunzmann niccokunzmann assigned stevepiercy

Sep 3, 2026

@coveralls-official

coveralls-official Bot commented Sep 3, 2026 •

edited

Loading

Copy link

Copy Markdown

Coverage Status

coverage: 97.562%. remained the same — AhmadBilalDSA:fix/typing-prop-components into collective:main

AhmadBilalDSA added 7 commits

September 4, 2026 15:22


 docs: convert docstrings to Google style in parser_tools and component (

6054e65

collective#1072)


 docs: add changelog entry for collective#1072 ( collective#1749 )

76f2f5d


 chore: move news fragment to docs/changelog/1749.doc.rst

f97f8b4


 chore: move news fragment to docs/changelog/1749.doc.rst ( collective#...

477436b

...1749)


 docs: add news fragment 1749.doc.rst and 1072.doc.rst

dc1c8b2


 docs: add towncrier news fragment at news/1072.documentation.rst ( col...

9d657db

...lective#1749)


 docs: revert Args to Parameters per style guide and format with ruff

b3d3465

AhmadBilalDSA force-pushed the fix/typing-prop-components branch from 6156865 to b3d3465 Compare

September 4, 2026 10:38

AhmadBilalDSA commented Sep 4, 2026 •

edited

Loading

Copy link

Copy Markdown

Author

Thanks for the feedback @stevepiercy and @angatha Reverted all Args: headings back to Parameters: across parser_tools.py and cal/component.py per the documentation guidelines. Updated the PR description from Fixes #1072 to See #1072. Formatted with ruff to ensure clean CI passing. Verified all unit tests pass locally with pytest."

@angatha

angatha self-requested a review

September 4, 2026 10:57

AhmadBilalDSA requested a review from stevepiercy

September 4, 2026 11:23

@stevepiercy


 Merge branch 'main' into fix/typing-prop-components

f97810a

@stevepiercy

stevepiercy commented Sep 6, 2026

Copy link

Copy Markdown

Member

@AhmadBilalDSA your edit to the description is worse. Please change it as @angatha directed, and see https://github.com/collective/icalendar/blob/main/.github/pull_request_template.md?plain=1#L14-L35 for instructions.

stevepiercy

stevepiercy requested changes

Sep 6, 2026

View reviewed changes

@stevepiercy stevepiercy left a comment

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

@AhmadBilalDSA thanks for your first contribution to icalendar! While reviewing your changes, I found old things that also needed to be addressed that were overlooked. Would you please take care? Thank you!

news/1749.documentation.rst

@@ -0,0 +1 @@

Apply Google Style docstrings to ``parser_tools.py`` and ``cal/component.py``. (#1072)

@stevepiercy stevepiercy Sep 6, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

Follow instructions at https://icalendar.readthedocs.io/en/latest/contribute/index.html#write-a-good-change-log-entry and see the note https://icalendar.readthedocs.io/en/latest/contribute/index.html#change-log-entry-file-name.

src/icalendar/cal/component.py Outdated

src/icalendar/cal/component.py

src/icalendar/cal/component.py Outdated

src/icalendar/parser_tools.py Outdated

AhmadBilalDSA and others added 12 commits

September 7, 2026 00:11


 docs: rename news fragment to PR 1749

f77ddbd


 Apply suggestion from @stevepiercy

c19c3da

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/parser_tools.py

7f0a9f6

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/parser_tools.py

08393c1

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/parser_tools.py

4aa8354

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/cal/component.py

fcdc71f

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/cal/component.py

0648b96

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/cal/component.py

e76e222

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/cal/component.py

e144079

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Update src/icalendar/cal/component.py

f25b927

Co-authored-by: Steve Piercy <web@stevepiercy.com>


 Merge branch 'main' into fix/typing-prop-components

6335df6


 typing: add type hints to Component.walk ( collective#938 , collective#...

863d389

...1749)

AhmadBilalDSA commented Sep 6, 2026

Copy link

Copy Markdown

Author

Hi @stevepiercy @angatha,

Updated the PR description to use See #1072.
Renamed the changelog fragment to news/1749.documentation.rst.
Applied all requested docstring grammar and formatting improvements across cal/component.py and parser_tools.py.
Added type hints and docstring updates to Component.walk (name: str | None = None, select: Callable[[Component], bool] = __identity) -> list[Component]) per Add type hints [beginner, Python, typing] #938 .