Friendlier Attendee APIs in iCalendar

Status: Merged
Period: Merged upstream on 2026-08-25
Confidentiality: Public. Public merged contribution. I've kept upstream ownership and the complete recorded AI-assistance disclosure visible in the case study.

Added convenient email-string inputs while preserving typed addresses, parameters, list identity, serialization, and factory behavior.

I implemented attendee normalization across Event, Todo, Journal, and Alarm APIs so callers can use ordinary email strings without losing typed-address behavior or existing parameters. The accepted contribution preserved red/green TDD history, updated typing and documentation, and responded to maintainer review while retaining the upstream AI-assistance disclosure.

Type: Open Source
Categories: Open Source
Software & Automation
Technologies: Python
pytest
Sphinx
Vale
iCalendar

Context

Python developers using iCalendar component APIs and maintainers preserving backward compatibility.

Existing typed objects and their parameters must remain intact.
Mutable-list identity and component-factory behavior must remain compatible.
The upstream AI-assistance disclosure must remain attached to the story.

Problem

Callers could not consistently pass ordinary email strings as attendees even though the library already understood address normalization, and any ergonomic fix had to preserve typed values, parameters, identity, and serialization.

My contribution

I implemented email-string normalization, preserved existing `vCalAddress` objects and parameters, retained mutable-list identity, applied the behavior across direct assignment and factory APIs, and updated typing, documentation, examples, release notes, and tests.

Approach

Establish the missing behavior through failing tests, normalize through the library's existing typed address path, preserve compatible inputs and identity semantics, then align documentation and tests with maintainer feedback.

Outcomes

Merged upstream.
The PR reported 16,104 passing tests, 367 documentation doctests, multi-version Python coverage, and successful documentation and change checks.

Limitations and current status