typing: add type hints to parser helper functions (#938) - #1743

Open

DaBestCode wants to merge 1 commit into

collective:main from

DaBestCode:type-hints-parser

Open

typing: add type hints to parser helper functions (#938) #1743
DaBestCode wants to merge 1 commit into
collective:main from
DaBestCode:type-hints-parser

Conversation

@DaBestCode

@DaBestCode DaBestCode commented Aug 31, 2026

Copy link

Copy Markdown

Linked issue

Contributes to Add type hints [beginner, Python, typing] #938

Description

This pull request adds comprehensive type hints to parser helper functions in the icalendar library, contributing to issue #938's goal of adding type hints throughout the codebase.

Changes Made

src/icalendar/parser_tools.py:
- Enhanced to_unicode() docstring with a "Returns" section to better document the function's return behavior
src/icalendar/parser/parameter.py:
- Added return type annotation -> Callable to the single_string_parameter() decorator function
- Added parameter type annotation upper: bool = False to clarify the upper parameter's type
- Added return type hints to inner functions:
  - decorator(): -> property
  - fget(): -> str | None (getter returns optional string)
  - fset(): -> None (setter returns None)
  - fdel(): -> None (deleter returns None)
news/938.chore.2:
- Added changelog entry documenting the type hint improvements

Benefits

Improved IDE autocompletion and type checking support
Better documentation through explicit type hints
Compatibility with static type checkers (mypy, pyright, etc.)
No changes to runtime behavior or logic

Checklist

I added a change log entry, following the instructions in all subsections under Change log requirements.
I followed icalendar's Artificial intelligence policy and disclosed my Responsible AI use in my commit messages, if applicable.
I ran and ensured all tests pass locally by following Run tests.

Additional information

All existing tests pass (pytest src/icalendar/tests/test_unit_parser_tools.py and parameter-related tests)
Type hints follow PEP 484 conventions using Python 3.10+ union syntax (|)
Changes are backward compatible and contain no breaking changes

@openhands-agent


 docs: add news entry for type hints in parser module

f57bc6f

@DaBestCode

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

August 31, 2026 05:15

@github-actions

github-actions Bot commented Aug 31, 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 added the ai-suspicion label

Aug 31, 2026

@github-actions

github-actions Bot commented Aug 31, 2026

Copy link

Copy Markdown

Contributor

Profile summary:

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

Full profile

GitHub user: DaBestCode
🟢 No concerns found with user's profile.
 🟢 Account age: 2 years
 🟢 Profile information:
 name: Pruthvi Nandan Janga
 blog: https://myportfolio-phi-ebon.vercel.app/
 email: pjanga@asu.edu
 bio: LeetCode Freak
 linkedin: https://www.linkedin.com/in/pruthvi-janga-9609a3238
 Empty fields: company, location
🟢 No concerns found with recent PR activity.
 1 PR opened in the last 21 days.
 0 opened against repos the user owns.
 0 opened against repos in publicly associated orgs.
 1 opened against external repos.
 🟢 0 of 1 external PRs merged in the last 21 days.
 🟢 0 of 1 external PRs closed without merging in the last 21 days.
🟢 No concerns found with recent issue activity.
 🟢 No new issues opened in the last 21 days.

@read-the-docs-community

read-the-docs-community Bot commented Aug 31, 2026

Copy link

Copy Markdown

Documentation build overview

📚 icalendar | 🛠️ Build #34305970 | 📁 Comparing f57bc6f against latest (59da8b8)

🔍 Preview build

4 files changed

± _modules/icalendar/parser_tools.html
± reference/api/icalendar.parser.parameter.html
± reference/api/icalendar.parser_tools.html
± _modules/icalendar/parser/parameter.html

@stevepiercy

stevepiercy commented Aug 31, 2026

Copy link

Copy Markdown

Member

CI fails == no review

@DaBestCode please follow our contributing guidelines. Thank you!

niccokunzmann

niccokunzmann requested changes

Sep 2, 2026

View reviewed changes

@niccokunzmann niccokunzmann 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.

Thanks! The change looks technically valid!

Could you give more detail about the AI use, please?

news/938.chore.2

@@ -0,0 +1 @@

Added type annotations to :func:`~icalendar.parser.parameter.single_string_parameter` and expanded docstrings in :mod:`icalendar.parser_tools`. I used AI to assist me with this change. (Issue #938)

@niccokunzmann niccokunzmann Sep 2, 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.

Hi, please mention the model that you used.

@niccokunzmann niccokunzmann assigned stevepiercy

Sep 2, 2026

@niccokunzmann

niccokunzmann commented Sep 2, 2026

Copy link

Copy Markdown

Member

@stevepiercy over to you: Have a look at the small docs change or just merge it when the changelog entry is ok for you.

@niccokunzmann

niccokunzmann commented Sep 2, 2026

Copy link

Copy Markdown

Member

@DaBestCode Welcome to icalendar! Nice to review your PR :)

Could you please format the code? We use a code formatter so that it always looks reliably the same. Please see here. https://github.com/collective/icalendar/actions/runs/33359907834/job/99389117324?pr=1743

stevepiercy

stevepiercy requested changes

Sep 6, 2026

View reviewed changes

news/938.chore.2

@@ -0,0 +1 @@

Added type annotations to :func:`~icalendar.parser.parameter.single_string_parameter` and expanded docstrings in :mod:`icalendar.parser_tools`. I used AI to assist me with this change. (Issue #938)

@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.

Don't include the issue number, as it's included in the filename. Also give yourself credit.

Suggested change

Added type annotations to :func:`~icalendar.parser.parameter.single_string_parameter` and expanded docstrings in :mod:`icalendar.parser_tools`. I used AI to assist me with this change. (Issue #938)

Added type annotations to :func:`~icalendar.parser.parameter.single_string_parameter` and expanded docstrings in :mod:`icalendar.parser_tools`. I used AI to assist me with this change. @DaBestCode

@stevepiercy

stevepiercy requested a review from niccokunzmann

September 6, 2026 10:37

@stevepiercy stevepiercy assigned niccokunzmann

Sep 6, 2026

Labels

ai-suspicion

4 participants

@DaBestCode @stevepiercy @niccokunzmann @openhands-agent

Uh oh!

Uh oh!

Conversation

@DaBestCode DaBestCode commented Aug 31, 2026

Linked issue

Description

Changes Made

Benefits

Checklist

Additional information

Uh oh!

github-actions Bot commented Aug 31, 2026

Uh oh!

github-actions Bot commented Aug 31, 2026

Uh oh!

read-the-docs-community Bot commented Aug 31, 2026

Documentation build overview

Uh oh!

stevepiercy commented Aug 31, 2026

Uh oh!

@niccokunzmann niccokunzmann left a comment

Choose a reason for hiding this comment

Uh oh!

@niccokunzmann niccokunzmann Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

niccokunzmann commented Sep 2, 2026

Uh oh!

niccokunzmann commented Sep 2, 2026

Uh oh!

@stevepiercy stevepiercy Sep 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants