Skip to content

Validate UID value on set (#1929) - #1940

Open
Siddharth-singla wants to merge 30 commits into
PyCalendar:mainfrom
Siddharth-singla:fix/1929-validate-uid-format
Open

Siddharth-singla wants to merge 30 commits into
PyCalendar:mainfrom
Siddharth-singla:fix/1929-validate-uid-format

Conversation

@Siddharth-singla

@Siddharth-singla Siddharth-singla commented Oct 14, 2026 •

Copy link
Copy Markdown

Linked issue

Description

The UID setter on components now validates the value when it is set, instead of silently storing anything.

RFC 5545 section 3.8.4.7 defines the UID value type as text, so the setter accepts any non-empty text, including the common local@domain form used across the spec and this project's own fixtures. It rejects only values that cannot be serialized into a valid calendar: an empty value, or one with control characters such as CR/LF. The value is never modified, so letter casing is preserved, as the issue requested.

The iana-token and "less than 255 octets" wording from RFC 7986 section 5.3 is a recommendation for generated identifiers, not a constraint on all accepted values, so it is documented but not enforced; enforcing it would reject valid at-sign-containing UIDs the parser already accepts.

Parsing is unaffected, because from_ical does not go through the property setter.

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 added or updated tests, if applicable.
  • I ran and ensured all tests pass locally by following Run tests.
  • I added or edited documentation as necessary, following the Style guide.

@github-actions github-actions Bot added the ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding. label Oct 14, 2026
@github-actions

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.

@Siddharth-singla
Siddharth-singla force-pushed the fix/1929-validate-uid-format branch 2 times, most recently from 3b682de to 7f94652 Compare October 14, 2026 11:52
The UID setter now validates assigned values as RFC 5545 section 3.8.4.7
'text', rejecting empty values and control characters (such as CR/LF)
that would otherwise produce an invalid calendar. Valid identifiers,
including the common local@domain form, are accepted unchanged so letter
casing is preserved. Parsing is unaffected because it does not go through
the property setter.

Adds a validate hook to single_string_property, a validate_uid helper,
docstring documentation, tests, and a changelog fragment.

AI disclosure (per icalendar AI policy):
Model: Kiro agent (Auto model selection).
How used: I asked the assistant to find a good first issue, investigate
the icalendar codebase, and draft a fix for issue PyCalendar#1929. The assistant
analysed the UID property/setter, identified that RFC 5545 defines UID as
'text' (not iana-token, so local@domain UIDs must stay valid), and
proposed validating only against empty values and control characters. I
reviewed the design and code, which I understand and take responsibility
for.
Prompt summary: "Find a good first issue, help me solve it, and prepare a
contribution" -> issue PyCalendar#1929; "implement the UID setter validation
following the repo conventions"; "fix the failing doctest and docs build".
@Siddharth-singla
Siddharth-singla force-pushed the fix/1929-validate-uid-format branch from 7f94652 to fa2a806 Compare October 14, 2026 11:56

@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 for the PR! That helps reason about idea.

Comment thread src/icalendar/attr.py Outdated
Setting the value to None will delete it.
"""
if value is not None and validate is not None:
validate(str(value))

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.

Suggested change
validate(str(value))
validate(value)

That str() is a good idea.
Though that introduces other problems. Let's say we set this to object() - does it validate then?

Could you add a type check to make sure that value is None or str? That would raise TypeError and needs testing. It should work...

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.

This still is not addressed. Please ask me if I am not clear.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

The setter now raises TypeError for anything other than None, str or UUID, with tests for object(), int, float, list and dict. This thread is anchored to the older diff, so it may be showing the earlier code. Which part is still open for you? I think it may be either that you'd like validate(value) with only str accepted, or that UUID shouldn't be accepted. Happy to change either.

Comment thread src/icalendar/attr.py Outdated

#: Control characters that are not allowed in an :rfc:`5545` ``text`` value.
#: Everything except TAB (``\t``) in the C0 range, plus DEL and the C1 range.
_UID_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0a-\x1f\x7f-\x9f]")

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 have a look at the issue again and which characters to allow for setting.

Also, I must correct, we cannot use the UID property for this but it needs to be a uid property.
See https://icalendar.readthedocs.io/en/stable/explanation/api-design.html#property-naming-convention

So, could you create a new one that enforces the RFC 7986 format?

@github-actions

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.

@niccokunzmann

Copy link
Copy Markdown
Member

Hi, please do not worry about the failing agent scan.

stevepiercy and others added 3 commits October 14, 2026 13:52
The UID setter now raises TypeError for values that are not a string,
UUID, or None, instead of coercing them with str(). validate_uid now
enforces the RFC 7986 section 5.3 rules: an RFC 5545 iana-token (ASCII
letters, digits and hyphens) shorter than 255 octets. The value is not
modified, so letter casing is preserved. Tests updated accordingly.

AI disclosure (per icalendar AI policy): I used an AI assistant to help
me understand the maintainer feedback, locate the relevant code, and
draft these changes. I reviewed and ran the changes myself and
understand them.
Update the UID docstring example and error message to match the new
RFC 7986 iana-token validation, shorten the error message to satisfy the
line-length limit, and apply ruff formatting.

AI disclosure (per icalendar AI policy): I used an AI assistant to help
me locate and fix the failing doctest and formatting issues. I reviewed
and ran the changes myself and understand them.
@Siddharth-singla

Copy link
Copy Markdown
Author

I've pushed the first two changes:

Type check — the setter now raises TypeError for values that aren't str, UUID, or None, instead of coercing with str(). Added tests for object(), int, float, list, dict.

Format — validate_uid now enforces the RFC 7986 §5.3 rules: an RFC 5545 iana-token (ASCII letters, digits, hyphens) under 255 octets, with casing preserved.

Implementing the strict iana-token rule surfaced something I'd like your guidance on: it rejects UIDs containing spaces, @, or dots. For example, test_issue_843_new_method_for_components.py sets a UID of "test UID" (with a space), which now fails. More broadly, @-style UIDs like event-1@example.com appear in several fixtures. Parsing isn't affected (it doesn't go through the setter), but direct assignment now raises for these.

This seems related to your point about UID vs uid: should I (a) add a raw uppercase UID passthrough property with no validation, and make the lowercase uid the validating layer that delegates to it (mirroring DTSTART/start), so strict validation only applies on the uid path? And how strict do you want it — should "test UID"-style values stay valid, or is rejecting them intended? Happy to adjust the existing test once the direction is clear.

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

Thank you! This looks technically really good.

I have a few suggestions. Could you have a look?

COMPONENTS = [Calendar, Event, Journal, Todo]


@pytest.mark.parametrize("cls", COMPONENTS)

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.

components here can be a fixture that can be re-used across all test cases.

Comment thread src/icalendar/attr.py Outdated
if _UID_IANA_TOKEN.match(value) is None:
raise InvalidCalendar(f"UID must be an RFC 5545 iana-token, got {value!r}")

"""Validate that ``value`` is a well-formed UID.

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.

This looks like a copy&paste section. Could you check?

Comment thread src/icalendar/attr.py Outdated
Comment on lines +974 to +975
:exc:`~icalendar.error.InvalidCalendar`. The value is validated but never
modified, so its letter casing is preserved.

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.

Suggested change
:exc:`~icalendar.error.InvalidCalendar`. The value is validated but never
modified, so its letter casing is preserved.
:exc:`~icalendar.error.InvalidCalendar`.

I think, this is not describing the format.

Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr.py Outdated
if _UID_IANA_TOKEN.match(value) is None:
raise InvalidCalendar(f"UID must be an RFC 5545 iana-token, got {value!r}")

"""Validate that ``value`` is a well-formed UID.

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.

This looks like a copy&paste section. Could you check?

Comment thread src/icalendar/attr.py Outdated
"""Create a property to access a single string value."""
"""Create a property to access a single string value.

Args:

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.

Could you also describe the existing parameters and use Parameters, see our style guide.

@Siddharth-singla

Copy link
Copy Markdown
Author

Thanks for the detailed review! I've addressed all the suggestions:

Removed the copy&paste leftover and the stale comment
Documented all parameters of single_string_property with a Parameters: section
Converted the component list to a reusable fixture
Trimmed the format docstring line and added a recommended UUID4 example
The docstring/news now correctly describe iana-token validation (thanks @faresrafat3 for catching the earlier mismatch)
The only remaining CI failures are in test_issue_843, which sets uid = "test UID" (with a space) — exactly the case from my earlier question. I've held off changing it until you confirm the direction: should strict iana-token reject such values (I'll update that test), or should the raw UID stay permissive with validation only on a separate uid property? Happy to implement either once you confirm.

@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 for work! I added more comments.

Have a look at icalendar.parser.string. It might be that some of that functionality can be merged.

Comment thread src/icalendar/attr.py Outdated
Comment on lines +501 to +502
name: The iCalendar property name (e.g. ``"UID"``).
docs: Documentation string for the generated property.

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 have a look at our style guide. I think we need to write (Reguired) or someting like that.

_UID_MAX_OCTETS = 255


def validate_uid(value: str) -> None:

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.

We validate iana tokens in many places now. It would be good to have all of that in one place. Can you move this into icalendar.parser.string - that is where we collect these different validation and corrections at this point in time. It might still move...

Comment thread src/icalendar/attr.py Outdated
)

#: An :rfc:`5545` ``iana-token``: one or more ASCII letters, digits or hyphens.
_UID_IANA_TOKEN = re.compile(r"^[A-Za-z0-9-]+$")

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.

When moving, please rename it to _RFC_5545_IANA_TOKEN_REGEX

Comment thread src/icalendar/attr.py Outdated
>>> from icalendar import Event
>>> from uuid import uuid4
>>> event = Event()
>>> event.uid = str(uuid4())

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.

Suggested change
>>> event.uid = str(uuid4())
>>> event.uid = uuid4()

Does that also work?

Comment thread src/icalendar/attr.py Outdated
>>> from uuid import uuid4
>>> event = Event()
>>> event.uid = str(uuid4())
>>> len(event.uid) > 0

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.

I think, we have patched that for the doctests, so it should always be the same.

Suggested change
>>> len(event.uid) > 0
>>> event.uid

Can you try this out?

Comment thread src/icalendar/attr.py Outdated
Comment on lines +989 to +994
>>> from icalendar import Event
>>> event = Event()
>>> event.uid = "AbC-123" # a valid token, casing is preserved
>>> print(event.uid)
AbC-123
>>> event.uid = "a b"

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.

Suggested change
>>> from icalendar import Event
>>> event = Event()
>>> event.uid = "AbC-123" # a valid token, casing is preserved
>>> print(event.uid)
AbC-123
>>> event.uid = "a b"
>>> event.uid = "a b"

This can build on top of the other docs above.

)
def test_invalid_uid_is_rejected(cls, value):
"""A value that cannot be serialized raises :exc:`InvalidCalendar`."""
component = cls()

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.

This is really nice. You have so many nice error messages in the validation function.
Could you parametrize this so that you also check for the error messages?
Then it is easier to see to which values they correspond.

- Move _RFC_5545_IANA_TOKEN_REGEX into icalendar.parser.string so the
  iana-token pattern lives alongside other string validation helpers;
  _UID_IANA_TOKEN in attr.py is now an alias for that shared constant.
- Add (Required)/(Optional) annotations to single_string_property
  Parameters: docstring per project style guide.
- Parametrize test_invalid_uid_is_rejected with (value, match) tuples
  so each invalid input is checked against its exact error message.
- Update uid doctest: pass uuid4() directly (no str() wrapper) and
  show event.uid with +ELLIPSIS; chain the casing/invalid examples
  onto the same event instance to avoid redundant setup.
@niccokunzmann

niccokunzmann commented Oct 21, 2026 •

Copy link
Copy Markdown
Member

@Siddharth-singla Let me know when you would like me to have another look. I will be offline for this night.

@Siddharth-singla

Copy link
Copy Markdown
Author

@niccokunzmann Thanks! I've addressed all the latest review comments — ready for another look when you're back:

Moved the iana-token regex into icalendar.parser.string as _RFC_5545_IANA_TOKEN_REGEX and use it directly in validate_uid.
Marked required/optional parameters in the single_string_property docstring.
Parametrized the invalid-UID test to also assert the error messages.
Simplified the UID doctest examples (uuid4() directly, event.uid, and the invalid example builds on the ones above).
One thing I noticed while moving the regex: parser/string.py already has a validate_token + NAME = re.compile(r"[\w.-]+"). That's intentionally broader than a strict iana-token — it allows . and _ (the comment notes it's for vCard), and it raises ValueError rather than InvalidCalendar. I kept the two separate for now rather than merge them, since unifying would change behaviour for existing callers. Happy to merge them if you'd prefer — just let me know which semantics should win.

One open question blocking CI: test_issue_843 sets uid = "test UID" (with a space), which the strict iana-token rule now rejects — that's the only remaining 3.14 / sdist failure. Should I update that test to use a valid token (treating strict validation as intended), or did you want the raw UID to stay permissive with validation only on a separate uid property? I'll implement whichever you prefer.

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

Hi, please reply in my comments and check if they are resolved. Let me know what I can do.

Comment thread src/icalendar/attr/__init__.py Outdated
"""Create a property to access a single string value.

Parameters:
name (Required): The iCalendar property name (e.g. ``"UID"``).

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 have a look at our style guide. If you have questions, let me know.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Fixed in 9ab75a0: the Parameters block now follows the style guide. I used the Required. prefix instead of (Required), put required parameters first with each group in alphabetical order, and dropped the (Optional) markers

Comment thread src/icalendar/attr.py Outdated
Setting the value to None will delete it.
"""
if value is not None and validate is not None:
validate(str(value))

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.

This still is not addressed. Please ask me if I am not clear.

@stevepiercy stevepiercy self-assigned this Nov 12, 2026

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

Thanks for your contribution. I reviewed docstrings and the news fragment, and made some suggestions for you to consider. Would you please take care? Thank you!

Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread news/1929.bugfix Resolved
Siddharth-singla and others added 7 commits November 14, 2026 19:49
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Comment thread news/1929.bugfix Resolved
Siddharth-singla and others added 2 commits November 14, 2026 19:51
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
@stevepiercy

Copy link
Copy Markdown
Member

@Siddharth-singla please update your branch to main. The docs build should then pass.

Applying the batched suggestion replaced only part of the old UID
docstring, which left an unterminated string and a syntax error.
Remove the old docstring and drop the reference suffix from the
:meth: roles.

AI disclosure (per icalendar AI policy):
Model: Kiro agent, Claude Sonnet 5.5 (0a88193, 9ab75a0) and
Claude Opus 5.5 (this commit).
How used: the assistant drafted the Parameters block in 0a88193,
the indentation fix in 9ab75a0, and found the leftover docstring and
role syntax fixed here. I reviewed and applied all changes.
Updated UID property docstring for clarity.
@Siddharth-singla

Copy link
Copy Markdown
Author

Applied your suggestions and updated the branch to main. Two follow-ups: applying the batched UID docstring suggestion left part of the old docstring behind, which broke the build, so I removed it in 96d214e. I also dropped "as a property" from the summary line in 35c1741 to fit ruff's 88-character limit.

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

Comment thread src/icalendar/attr/__init__.py Resolved
Comment thread src/icalendar/attr/__init__.py Resolved
Co-authored-by: Steve Piercy <web@stevepiercy.com>

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

I approve. Back over to @niccokunzmann for a final review. Thank you!

@Siddharth-singla

Copy link
Copy Markdown
Author

Thanks! One catch: setting the UID to "" raises InvalidCalendar, because an iana-token needs at least one character, and there's a test for that case in test_issue_1929_uid_format.py. Only None clears it. Should I change the sentence to "To clear the value, set it to None.", or should "" clear it too? @niccokunzmann

This branch has not been deployed

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

Labels

ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Enforce UID format for setters

4 participants