Repository navigation
Validate UID value on set (#1929) - #1940
Siddharth-singla wants to merge 30 commits into
Conversation
|
This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments. |
3b682de to
7f94652
Compare
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".
7f94652 to
fa2a806
Compare
niccokunzmann
left a comment
There was a problem hiding this comment.
Thanks for the PR! That helps reason about idea.
| Setting the value to None will delete it. | ||
| """ | ||
| if value is not None and validate is not None: | ||
| validate(str(value)) |
There was a problem hiding this comment.
| 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...
There was a problem hiding this comment.
This still is not addressed. Please ask me if I am not clear.
There was a problem hiding this comment.
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.
|
|
||
| #: 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]") |
There was a problem hiding this comment.
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?
|
This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments. |
|
Hi, please do not worry about the failing agent scan. |
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.
|
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
left a comment
There was a problem hiding this comment.
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) |
There was a problem hiding this comment.
components here can be a fixture that can be re-used across all test cases.
| 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. |
There was a problem hiding this comment.
This looks like a copy&paste section. Could you check?
| :exc:`~icalendar.error.InvalidCalendar`. The value is validated but never | ||
| modified, so its letter casing is preserved. |
There was a problem hiding this comment.
| :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.
| 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. |
There was a problem hiding this comment.
This looks like a copy&paste section. Could you check?
| """Create a property to access a single string value.""" | ||
| """Create a property to access a single string value. | ||
|
|
||
| Args: |
There was a problem hiding this comment.
Could you also describe the existing parameters and use Parameters, see our style guide.
|
Thanks for the detailed review! I've addressed all the suggestions: Removed the copy&paste leftover and the stale comment |
niccokunzmann
left a comment
There was a problem hiding this comment.
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.
| name: The iCalendar property name (e.g. ``"UID"``). | ||
| docs: Documentation string for the generated property. |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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...
| ) | ||
|
|
||
| #: An :rfc:`5545` ``iana-token``: one or more ASCII letters, digits or hyphens. | ||
| _UID_IANA_TOKEN = re.compile(r"^[A-Za-z0-9-]+$") |
There was a problem hiding this comment.
When moving, please rename it to _RFC_5545_IANA_TOKEN_REGEX
| >>> from icalendar import Event | ||
| >>> from uuid import uuid4 | ||
| >>> event = Event() | ||
| >>> event.uid = str(uuid4()) |
There was a problem hiding this comment.
| >>> event.uid = str(uuid4()) | |
| >>> event.uid = uuid4() |
Does that also work?
| >>> from uuid import uuid4 | ||
| >>> event = Event() | ||
| >>> event.uid = str(uuid4()) | ||
| >>> len(event.uid) > 0 |
There was a problem hiding this comment.
I think, we have patched that for the doctests, so it should always be the same.
| >>> len(event.uid) > 0 | |
| >>> event.uid |
Can you try this out?
| >>> 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" |
There was a problem hiding this comment.
| >>> 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() |
There was a problem hiding this comment.
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.
|
@Siddharth-singla Let me know when you would like me to have another look. I will be offline for this night. |
|
@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. 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
left a comment
There was a problem hiding this comment.
Hi, please reply in my comments and check if they are resolved. Let me know what I can do.
| """Create a property to access a single string value. | ||
|
|
||
| Parameters: | ||
| name (Required): The iCalendar property name (e.g. ``"UID"``). |
There was a problem hiding this comment.
Please have a look at our style guide. If you have questions, let me know.
There was a problem hiding this comment.
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
| Setting the value to None will delete it. | ||
| """ | ||
| if value is not None and validate is not None: | ||
| validate(str(value)) |
There was a problem hiding this comment.
This still is not addressed. Please ask me if I am not clear.
Reordered parameter documentation for clarity.
stevepiercy
left a comment
There was a problem hiding this comment.
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!
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>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
|
@Siddharth-singla please update your branch to |
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.
|
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
left a comment
There was a problem hiding this comment.
Docs look great, except for two of my mistakes. Lesson to learn: maintainers aren't perfect. I'll
- https://icalendar--1940.org.readthedocs.build/en/1940/reference/api/icalendar.attr.html#icalendar.attr.single_string_property
- https://icalendar--1940.org.readthedocs.build/en/1940/reference/api/icalendar.attr.html#icalendar.attr.validate_uid
I also noticed that with the latest version of sphinx-autodoc-typehints, there's a new trailing section heading "Setter accepts". That's interesting. @niccokunzmann didn't you want this for some time?
- https://icalendar--1940.org.readthedocs.build/en/1940/reference/api/icalendar.cal.event.html#icalendar.cal.event.Event.uid
- https://icalendar--1940.org.readthedocs.build/en/1940/reference/api/icalendar.cal.journal.html#icalendar.cal.journal.Journal.uid
- https://icalendar--1940.org.readthedocs.build/en/1940/reference/api/icalendar.cal.todo.html#icalendar.cal.todo.Todo.uid
Co-authored-by: Steve Piercy <web@stevepiercy.com>
stevepiercy
left a comment
There was a problem hiding this comment.
I approve. Back over to @niccokunzmann for a final review. Thank you!
|
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 |
Linked issue
Description
The
UIDsetter 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