From 77691858795b64c2502ee4d1d9c907b981a70268 Mon Sep 17 00:00:00 2001 From: Raj Gahoi Date: Sat, 24 Oct 2026 19:26:33 +0530 Subject: [PATCH 1/4] feat(cal/todo): add COMPLETED property to VTODO (#1797) --- src/icalendar/cal/todo.py | 37 ++++++++++ .../calendars/issue_1797_todo_completed.ics | 13 ++++ src/icalendar/tests/test_todo_completed.py | 69 +++++++++++++++++++ 3 files changed, 119 insertions(+) create mode 100644 src/icalendar/tests/calendars/issue_1797_todo_completed.ics create mode 100644 src/icalendar/tests/test_todo_completed.py diff --git a/src/icalendar/cal/todo.py b/src/icalendar/cal/todo.py index 01b23c766..42ca26fd2 100644 --- a/src/icalendar/cal/todo.py +++ b/src/icalendar/cal/todo.py @@ -44,6 +44,7 @@ set_duration_with_locking, set_end_with_locking, set_start_with_locking, + single_utc_property, status_property, summary_property, uid_property, @@ -172,6 +173,42 @@ class Todo(Component): property_del_duration, property_doc_duration_template.format(component="VTODO"), ) + COMPLETED = single_utc_property( + "COMPLETED", + """Date-time when the todo was completed in UTC. + + This property is defined in :rfc:`5545#section-3.8.2.1`. It can be + specified in a completed "VTODO" calendar component. + + The value is always in UTC. + + Example: + .. code-block:: pycon + + >>> from datetime import datetime, timezone + >>> from icalendar import Todo + >>> todo = Todo() + >>> todo.COMPLETED = datetime(2007, 5, 1, 12, 0, 0, tzinfo=timezone.utc) + >>> todo.COMPLETED + datetime.datetime(2007, 5, 1, 12, 0, tzinfo=ZoneInfo(key='UTC')) + """, + ) + + @property + def completed(self) -> datetime | None: + """Date-time when the todo was completed, as a :class:`~datetime.datetime` in UTC. + + This is the lowercase property counterpart to, and accessor for, :attr:`COMPLETED`. + """ + return self.COMPLETED + + @completed.setter + def completed(self, value: datetime | None) -> None: + self.COMPLETED = value + + @completed.deleter + def completed(self) -> None: + del self.COMPLETED def _get_start_end_duration(self): """Verify the calendar validity and return the right attributes.""" diff --git a/src/icalendar/tests/calendars/issue_1797_todo_completed.ics b/src/icalendar/tests/calendars/issue_1797_todo_completed.ics new file mode 100644 index 000000000..3e3248b7c --- /dev/null +++ b/src/icalendar/tests/calendars/issue_1797_todo_completed.ics @@ -0,0 +1,13 @@ +BEGIN:VCALENDAR +VERSION:2.0 +PRODID:-//Example Corp.//CalDAV Client//EN +BEGIN:VTODO +UID:20070313T123432Z-456553@example.com +DTSTAMP:20070313T123432Z +COMPLETED;VALUE=DATE:20070501 +SUMMARY:Submit Quebec Income Tax Return for 2006 +CLASS:CONFIDENTIAL +CATEGORIES:FAMILY,FINANCE +STATUS:NEEDS-ACTION +END:VTODO +END:VCALENDAR diff --git a/src/icalendar/tests/test_todo_completed.py b/src/icalendar/tests/test_todo_completed.py new file mode 100644 index 000000000..50e911859 --- /dev/null +++ b/src/icalendar/tests/test_todo_completed.py @@ -0,0 +1,69 @@ +from datetime import datetime, timezone + +from icalendar import Calendar, Todo + + +def test_todo_completed_property(calendars): + """Test Todo.COMPLETED property access with fixture calendar.""" + cal = calendars.issue_1797_todo_completed + (todo,) = cal.todos + assert todo.COMPLETED == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) + assert todo.completed == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) + + +def test_todo_completed_without_value_parameter(): + """Test Todo.COMPLETED with date string without VALUE=DATE.""" + ics = """BEGIN:VCALENDAR +VERSION:2.0 +PRODID:-//Example Corp.//CalDAV Client//EN +BEGIN:VTODO +UID:20070313T123432Z-456553@example.com +DTSTAMP:20070313T123432Z +COMPLETED:20070501 +SUMMARY:Submit Quebec Income Tax Return for 2006 +CLASS:CONFIDENTIAL +CATEGORIES:FAMILY,FINANCE +STATUS:NEEDS-ACTION +END:VTODO +END:VCALENDAR""" + cal = Calendar.from_ical(ics) + (todo,) = cal.todos + assert todo.COMPLETED == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) + assert todo.completed == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) + + +def test_todo_completed_with_utc_datetime(): + """Test Todo.COMPLETED with explicit UTC datetime.""" + ics = """BEGIN:VCALENDAR +VERSION:2.0 +PRODID:-//Example Corp.//CalDAV Client//EN +BEGIN:VTODO +UID:20070313T123432Z-456553@example.com +DTSTAMP:20070313T123432Z +COMPLETED:20070501T133000Z +SUMMARY:Submit Quebec Income Tax Return for 2006 +END:VTODO +END:VCALENDAR""" + cal = Calendar.from_ical(ics) + (todo,) = cal.todos + assert todo.COMPLETED == datetime(2007, 5, 1, 13, 30, tzinfo=timezone.utc) + assert todo.completed == datetime(2007, 5, 1, 13, 30, tzinfo=timezone.utc) + + +def test_todo_completed_setter_and_deleter(): + """Test setter and deleter for Todo.COMPLETED and todo.completed.""" + todo = Todo() + assert todo.COMPLETED is None + assert todo.completed is None + + todo.completed = datetime(2024, 10, 24, 12, 0, tzinfo=timezone.utc) + assert todo.COMPLETED == datetime(2024, 10, 24, 12, 0, tzinfo=timezone.utc) + + del todo.completed + assert todo.COMPLETED is None + + todo.COMPLETED = datetime(2025, 1, 1, 0, 0, tzinfo=timezone.utc) + assert todo.completed == datetime(2025, 1, 1, 0, 0, tzinfo=timezone.utc) + + del todo.COMPLETED + assert todo.COMPLETED is None From 7a9bdc77fb4e47148c7b7d51def56398ef9de88e Mon Sep 17 00:00:00 2001 From: Raj Gahoi Date: Sat, 24 Oct 2026 20:33:52 +0530 Subject: [PATCH 2/4] docs(news): add news fragment for issue #1797 --- news/1797.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/1797.feature diff --git a/news/1797.feature b/news/1797.feature new file mode 100644 index 000000000..eaa880b1c --- /dev/null +++ b/news/1797.feature @@ -0,0 +1 @@ +Added ``COMPLETED`` property to ``Todo`` (VTODO) components per RFC 5545 section 3.8.2.1. - by @RajGahoi From 1e24a158cd61e7e1e33ba745fcadc89ccb17dbe8 Mon Sep 17 00:00:00 2001 From: Raj Gahoi Date: Sun, 25 Oct 2026 17:12:45 +0530 Subject: [PATCH 3/4] feat(cal/todo): align COMPLETED property with approved #1803 implementation (#1797) - Use single_utc_property without lowercase .completed alias - Support completed parameter in Todo.new() - Update Todo class docstring doctest to assert RFC-conformant COMPLETED serialization - Register COMPLETED in test_property_docstrings UTC_PROPERTIES - Add RFC 5545 and CalDAV VTODO fixture tests --- src/icalendar/cal/todo.py | 41 ++++----- ..._todo_completed.ics => todo_completed.ics} | 2 +- .../tests/test_issue_1797_todo_completed.py | 91 +++++++++++++++++++ .../tests/test_property_docstrings.py | 3 +- src/icalendar/tests/test_todo_completed.py | 69 -------------- src/icalendar/tests/todos/completed.ics | 9 ++ .../tests/todos/rfc5545_completed.ics | 5 + 7 files changed, 125 insertions(+), 95 deletions(-) rename src/icalendar/tests/calendars/{issue_1797_todo_completed.ics => todo_completed.ics} (90%) create mode 100644 src/icalendar/tests/test_issue_1797_todo_completed.py delete mode 100644 src/icalendar/tests/test_todo_completed.py create mode 100644 src/icalendar/tests/todos/completed.ics create mode 100644 src/icalendar/tests/todos/rfc5545_completed.ics diff --git a/src/icalendar/cal/todo.py b/src/icalendar/cal/todo.py index 42ca26fd2..5cb8a25d5 100644 --- a/src/icalendar/cal/todo.py +++ b/src/icalendar/cal/todo.py @@ -90,13 +90,13 @@ class Todo(Component): >>> from icalendar import Todo, STATUS >>> todo = Todo.example() >>> todo["PERCENT-COMPLETE"] = 100 - >>> todo["COMPLETED"] = datetime(2007, 5, 1, 12, tzinfo=timezone.utc) + >>> todo.COMPLETED = datetime(2007, 5, 1, 12, tzinfo=timezone.utc) >>> todo.status = STATUS.COMPLETED >>> print(todo.to_ical().decode()) BEGIN:VTODO CATEGORIES:FAMILY,FINANCE CLASS:CONFIDENTIAL - COMPLETED:2007-05-01 12:00:00+00:00 + COMPLETED:20070501T120000Z DTSTAMP:20070313T123432Z DUE;VALUE=DATE:20070501 PERCENT-COMPLETE:100 @@ -175,40 +175,30 @@ class Todo(Component): ) COMPLETED = single_utc_property( "COMPLETED", - """Date-time when the todo was completed in UTC. + """The date and time that a to-do was actually completed, per :rfc:`5545#section-3.8.2.1`. - This property is defined in :rfc:`5545#section-3.8.2.1`. It can be - specified in a completed "VTODO" calendar component. + This property defines the date and time that a to-do was actually completed. + The property can be specified in a "VTODO" calendar component. The value + MUST be specified as a date with UTC time. + Returns ``None`` when the to-do has not been marked as completed. The value is always in UTC. Example: .. code-block:: pycon - >>> from datetime import datetime, timezone + >>> from datetime import timezone, datetime >>> from icalendar import Todo + >>> UTC = timezone.utc >>> todo = Todo() - >>> todo.COMPLETED = datetime(2007, 5, 1, 12, 0, 0, tzinfo=timezone.utc) + >>> todo.COMPLETED = datetime(2007, 5, 1, 12, 0, tzinfo=UTC) >>> todo.COMPLETED datetime.datetime(2007, 5, 1, 12, 0, tzinfo=ZoneInfo(key='UTC')) - """, - ) - - @property - def completed(self) -> datetime | None: - """Date-time when the todo was completed, as a :class:`~datetime.datetime` in UTC. - This is the lowercase property counterpart to, and accessor for, :attr:`COMPLETED`. - """ - return self.COMPLETED - - @completed.setter - def completed(self, value: datetime | None) -> None: - self.COMPLETED = value - - @completed.deleter - def completed(self) -> None: - del self.COMPLETED + See also: + :attr:`STATUS` + """, + ) def _get_start_end_duration(self): """Verify the calendar validity and return the right attributes.""" @@ -373,6 +363,7 @@ def new( classification: CLASS | None = None, color: str | None = None, comments: list[str] | str | None = None, + completed: date | datetime | None = None, concepts: CONCEPTS_TYPE_SETTER = None, contacts: list[str] | str | None = None, conferences: list[Conference] | None = None, @@ -409,6 +400,7 @@ def new( classification: The :attr:`classification` of the todo. color: The :attr:`color` of the todo. comments: The :attr:`~icalendar.cal.component.Component.comments` of the todo. + completed: The :attr:`COMPLETED` date/time of the todo. concepts: The :attr:`~icalendar.cal.component.Component.concepts` of the todo. contacts: The :attr:`contacts` of the todo. conferences: The :attr:`conferences` of the todo. @@ -471,6 +463,7 @@ def new( todo.attachments = attachments todo.contacts = contacts todo.status = status + todo.COMPLETED = completed todo.REQUEST_STATUS = request_status todo.RESOURCES = resources todo.attendees = attendees diff --git a/src/icalendar/tests/calendars/issue_1797_todo_completed.ics b/src/icalendar/tests/calendars/todo_completed.ics similarity index 90% rename from src/icalendar/tests/calendars/issue_1797_todo_completed.ics rename to src/icalendar/tests/calendars/todo_completed.ics index 3e3248b7c..84afb0ac1 100644 --- a/src/icalendar/tests/calendars/issue_1797_todo_completed.ics +++ b/src/icalendar/tests/calendars/todo_completed.ics @@ -4,7 +4,7 @@ PRODID:-//Example Corp.//CalDAV Client//EN BEGIN:VTODO UID:20070313T123432Z-456553@example.com DTSTAMP:20070313T123432Z -COMPLETED;VALUE=DATE:20070501 +COMPLETED:20070501 SUMMARY:Submit Quebec Income Tax Return for 2006 CLASS:CONFIDENTIAL CATEGORIES:FAMILY,FINANCE diff --git a/src/icalendar/tests/test_issue_1797_todo_completed.py b/src/icalendar/tests/test_issue_1797_todo_completed.py new file mode 100644 index 000000000..3e63c0e57 --- /dev/null +++ b/src/icalendar/tests/test_issue_1797_todo_completed.py @@ -0,0 +1,91 @@ +"""Tests for issue #1797: Todo.COMPLETED property.""" + +from datetime import date, datetime, timezone +from zoneinfo import ZoneInfo + +import pytest + +from icalendar import Todo +from icalendar.error import InvalidCalendar + +UTC = ZoneInfo("UTC") + + +def test_todo_example_completed(todos): + """Test loading Todo example from todos/completed.ics.""" + todo = todos.completed + assert todo.name == "VTODO" + expected = datetime(2007, 5, 1, 0, 0, tzinfo=UTC) + assert todo.COMPLETED == expected + + +def test_calendar_todo_completed(calendars): + """Test loading calendar from calendars/todo_completed.ics.""" + todo = calendars.todo_completed.todos[0] + expected = datetime(2007, 5, 1, 0, 0, tzinfo=UTC) + assert todo.COMPLETED == expected + + +def test_rfc5545_completed_datetime_example(todos): + """Test parsing RFC 5545 section 3.8.2.1 example: COMPLETED:19960401T150000Z.""" + todo = todos.rfc5545_completed + assert todo.COMPLETED == datetime(1996, 4, 1, 15, 0, tzinfo=UTC) + + +def test_completed_get_set_del(): + """Test getting, setting, and deleting COMPLETED.""" + todo = Todo() + assert todo.COMPLETED is None + assert "COMPLETED" not in todo + + # Set UTC datetime via COMPLETED + dt_utc = datetime(2026, 9, 16, 12, 0, tzinfo=timezone.utc) + todo.COMPLETED = dt_utc + assert todo.COMPLETED == datetime(2026, 9, 16, 12, 0, tzinfo=UTC) + + # Delete via COMPLETED + del todo.COMPLETED + assert todo.COMPLETED is None + assert "COMPLETED" not in todo + + # Set date via COMPLETED + d = date(2026, 9, 16) + todo.COMPLETED = d + assert todo.COMPLETED == datetime(2026, 9, 16, 0, 0, tzinfo=UTC) + + # Set None via COMPLETED + todo.COMPLETED = None + assert todo.COMPLETED is None + assert "COMPLETED" not in todo + + +def test_todo_new_with_completed(): + """Test creating a new Todo with the completed parameter.""" + dt_utc = datetime(2026, 9, 16, 14, 30, tzinfo=timezone.utc) + todo = Todo.new(summary="Test Todo", completed=dt_utc) + assert todo.COMPLETED == datetime(2026, 9, 16, 14, 30, tzinfo=UTC) + + # With date + d = date(2026, 9, 16) + todo_date = Todo.new(summary="Test Todo", completed=d) + assert todo_date.COMPLETED == datetime(2026, 9, 16, 0, 0, tzinfo=UTC) + + # Without completed + todo_none = Todo.new(summary="Test Todo") + assert todo_none.COMPLETED is None + assert "COMPLETED" not in todo_none + + +def test_invalid_completed(): + """Test setting invalid types or invalid values raises appropriate errors.""" + todo = Todo() + with pytest.raises(TypeError): + todo.COMPLETED = "not a date" + + with pytest.raises(TypeError): + todo.COMPLETED = 12345 + + # Invalid value directly in component dict + todo["COMPLETED"] = 12345 + with pytest.raises(InvalidCalendar): + _ = todo.COMPLETED diff --git a/src/icalendar/tests/test_property_docstrings.py b/src/icalendar/tests/test_property_docstrings.py index 35f4867f5..c2957f594 100644 --- a/src/icalendar/tests/test_property_docstrings.py +++ b/src/icalendar/tests/test_property_docstrings.py @@ -15,7 +15,7 @@ import pytest -from icalendar.cal import Alarm, Availability, Available, Component, Event +from icalendar.cal import Alarm, Availability, Available, Component, Event, Todo #: iCalendar property name -> property object, as attached to its class UTC_PROPERTIES = { @@ -25,6 +25,7 @@ "ACKNOWLEDGED": Alarm.__dict__["ACKNOWLEDGED"], "X-MOZ-SNOOZE-TIME": Event.__dict__["X_MOZ_SNOOZE_TIME"], "X-MOZ-LASTACK": Event.__dict__["X_MOZ_LASTACK"], + "COMPLETED": Todo.__dict__["COMPLETED"], } diff --git a/src/icalendar/tests/test_todo_completed.py b/src/icalendar/tests/test_todo_completed.py deleted file mode 100644 index 50e911859..000000000 --- a/src/icalendar/tests/test_todo_completed.py +++ /dev/null @@ -1,69 +0,0 @@ -from datetime import datetime, timezone - -from icalendar import Calendar, Todo - - -def test_todo_completed_property(calendars): - """Test Todo.COMPLETED property access with fixture calendar.""" - cal = calendars.issue_1797_todo_completed - (todo,) = cal.todos - assert todo.COMPLETED == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) - assert todo.completed == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) - - -def test_todo_completed_without_value_parameter(): - """Test Todo.COMPLETED with date string without VALUE=DATE.""" - ics = """BEGIN:VCALENDAR -VERSION:2.0 -PRODID:-//Example Corp.//CalDAV Client//EN -BEGIN:VTODO -UID:20070313T123432Z-456553@example.com -DTSTAMP:20070313T123432Z -COMPLETED:20070501 -SUMMARY:Submit Quebec Income Tax Return for 2006 -CLASS:CONFIDENTIAL -CATEGORIES:FAMILY,FINANCE -STATUS:NEEDS-ACTION -END:VTODO -END:VCALENDAR""" - cal = Calendar.from_ical(ics) - (todo,) = cal.todos - assert todo.COMPLETED == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) - assert todo.completed == datetime(2007, 5, 1, 0, 0, tzinfo=timezone.utc) - - -def test_todo_completed_with_utc_datetime(): - """Test Todo.COMPLETED with explicit UTC datetime.""" - ics = """BEGIN:VCALENDAR -VERSION:2.0 -PRODID:-//Example Corp.//CalDAV Client//EN -BEGIN:VTODO -UID:20070313T123432Z-456553@example.com -DTSTAMP:20070313T123432Z -COMPLETED:20070501T133000Z -SUMMARY:Submit Quebec Income Tax Return for 2006 -END:VTODO -END:VCALENDAR""" - cal = Calendar.from_ical(ics) - (todo,) = cal.todos - assert todo.COMPLETED == datetime(2007, 5, 1, 13, 30, tzinfo=timezone.utc) - assert todo.completed == datetime(2007, 5, 1, 13, 30, tzinfo=timezone.utc) - - -def test_todo_completed_setter_and_deleter(): - """Test setter and deleter for Todo.COMPLETED and todo.completed.""" - todo = Todo() - assert todo.COMPLETED is None - assert todo.completed is None - - todo.completed = datetime(2024, 10, 24, 12, 0, tzinfo=timezone.utc) - assert todo.COMPLETED == datetime(2024, 10, 24, 12, 0, tzinfo=timezone.utc) - - del todo.completed - assert todo.COMPLETED is None - - todo.COMPLETED = datetime(2025, 1, 1, 0, 0, tzinfo=timezone.utc) - assert todo.completed == datetime(2025, 1, 1, 0, 0, tzinfo=timezone.utc) - - del todo.COMPLETED - assert todo.COMPLETED is None diff --git a/src/icalendar/tests/todos/completed.ics b/src/icalendar/tests/todos/completed.ics new file mode 100644 index 000000000..eb68b7592 --- /dev/null +++ b/src/icalendar/tests/todos/completed.ics @@ -0,0 +1,9 @@ +BEGIN:VTODO +UID:20070313T123432Z-456553@example.com +DTSTAMP:20070313T123432Z +COMPLETED;VALUE=DATE:20070501 +SUMMARY:Submit Quebec Income Tax Return for 2006 +CLASS:CONFIDENTIAL +CATEGORIES:FAMILY,FINANCE +STATUS:NEEDS-ACTION +END:VTODO diff --git a/src/icalendar/tests/todos/rfc5545_completed.ics b/src/icalendar/tests/todos/rfc5545_completed.ics new file mode 100644 index 000000000..fb8fe237f --- /dev/null +++ b/src/icalendar/tests/todos/rfc5545_completed.ics @@ -0,0 +1,5 @@ +BEGIN:VTODO +UID:20070313T123432Z-456553@example.com +DTSTAMP:20070313T123432Z +COMPLETED:19960401T150000Z +END:VTODO From da525e9fb07b98b9eb38a77a44529edbf08e55e3 Mon Sep 17 00:00:00 2001 From: Raj Gahoi Date: Wed, 18 Nov 2026 18:19:48 +0530 Subject: [PATCH 4/4] docs(todo): apply review suggestions for COMPLETED docstring and news fragment Signed-off-by: Raj Gahoi --- news/1797.feature | 2 +- src/icalendar/cal/todo.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/news/1797.feature b/news/1797.feature index eaa880b1c..f372cbb2f 100644 --- a/news/1797.feature +++ b/news/1797.feature @@ -1 +1 @@ -Added ``COMPLETED`` property to ``Todo`` (VTODO) components per RFC 5545 section 3.8.2.1. - by @RajGahoi +Added property :attr:`Todo.COMPLETED ` per :rfc:`5545#section-3.8.2.1`. @RajGahoi diff --git a/src/icalendar/cal/todo.py b/src/icalendar/cal/todo.py index 5cb8a25d5..8f600d54c 100644 --- a/src/icalendar/cal/todo.py +++ b/src/icalendar/cal/todo.py @@ -178,7 +178,7 @@ class Todo(Component): """The date and time that a to-do was actually completed, per :rfc:`5545#section-3.8.2.1`. This property defines the date and time that a to-do was actually completed. - The property can be specified in a "VTODO" calendar component. The value + The property can be specified in a VTODO calendar component. The value MUST be specified as a date with UTC time. Returns ``None`` when the to-do has not been marked as completed. @@ -196,7 +196,7 @@ class Todo(Component): datetime.datetime(2007, 5, 1, 12, 0, tzinfo=ZoneInfo(key='UTC')) See also: - :attr:`STATUS` + :attr:`status` """, )