From 6f5d956d2442e6592d2f2b1a39cca5ed81dea088 Mon Sep 17 00:00:00 2001 From: Rishabh Bafna Date: Wed, 18 Nov 2026 02:21:27 +0530 Subject: [PATCH] feat(todo): add COMPLETED and completed property accessors (closes #1797) --- news/+1797-todo-completed.feature | 1 + src/icalendar/cal/todo.py | 47 +++++++ .../tests/test_issue_1797_todo_completed.py | 133 ++++++++++++++++++ .../tests/todos/issue_1797_completed_date.ics | 9 ++ .../todos/issue_1797_completed_datetime.ics | 9 ++ 5 files changed, 199 insertions(+) create mode 100644 news/+1797-todo-completed.feature create mode 100644 src/icalendar/tests/test_issue_1797_todo_completed.py create mode 100644 src/icalendar/tests/todos/issue_1797_completed_date.ics create mode 100644 src/icalendar/tests/todos/issue_1797_completed_datetime.ics diff --git a/news/+1797-todo-completed.feature b/news/+1797-todo-completed.feature new file mode 100644 index 000000000..102487334 --- /dev/null +++ b/news/+1797-todo-completed.feature @@ -0,0 +1 @@ +Added :attr:`COMPLETED ` and :attr:`completed ` to access the :rfc:`5545#section-3.8.2.1` ``COMPLETED`` property of :class:`~icalendar.cal.todo.Todo`. @RishabhIIITD diff --git a/src/icalendar/cal/todo.py b/src/icalendar/cal/todo.py index 64fd73c41..c60d3ce12 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,28 @@ class Todo(Component): property_del_duration, property_doc_duration_template.format(component="VTODO"), ) + COMPLETED = single_utc_property( + "COMPLETED", + """The UTC datetime when this todo was completed, per :rfc:`5545#section-3.8.2.1`. + + This property defines the date and time that a to-do was actually completed. + This property is optional. + The value is always in UTC. It can also be accessed as :attr:`completed`. + + Example: + .. code-block:: pycon + + >>> from datetime import timezone, datetime + >>> from icalendar import Todo + >>> todo = Todo() + >>> todo.COMPLETED = datetime(2024, 6, 1, 12, 0, 0, tzinfo=timezone.utc) + >>> todo.COMPLETED + datetime.datetime(2024, 6, 1, 12, 0, tzinfo=ZoneInfo(key='UTC')) + + See also: + :attr:`completed`, :attr:`status`, :attr:`percent_complete` + """, + ) def _get_start_end_duration(self): """Verify the calendar validity and return the right attributes.""" @@ -240,6 +263,27 @@ def end(self, end: date | datetime | None): """ self.DUE = end + @property + def completed(self) -> datetime | None: + """The UTC datetime when this todo was completed, as a :class:`~datetime.datetime`. + + This is the lowercase property counterpart to, and accessor for, :attr:`COMPLETED`. + """ + return self.COMPLETED + + @completed.setter + def completed(self, completed: date | datetime | None): + """Set the completion datetime of the VTODO. + + Sets the ``COMPLETED`` property. Pass ``None`` to remove it. + """ + self.COMPLETED = completed + + @completed.deleter + def completed(self): + """Delete the ``COMPLETED`` property from the VTODO.""" + del self.COMPLETED + @property def duration(self) -> timedelta: """The duration of the VTODO. @@ -356,6 +400,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, @@ -392,6 +437,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` 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. @@ -443,6 +489,7 @@ def new( todo.uid = uid if uid is not None else uuid.uuid4() todo.start = start todo.end = end + todo.completed = completed todo.color = color todo.categories = categories todo.sequence = sequence 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..ab274f00b --- /dev/null +++ b/src/icalendar/tests/test_issue_1797_todo_completed.py @@ -0,0 +1,133 @@ +"""Test Todo.COMPLETED and Todo.completed property accessors. + +See https://github.com/PyCalendar/icalendar/issues/1797 +and RFC 5545 section 3.8.2.1. +""" + +from datetime import date, datetime, timezone + +from icalendar import Calendar, Event, Journal, Todo +from icalendar.timezone import tzp + +UTC = timezone.utc + + +def test_todo_completed_from_date_example_1(): + """Example 1: COMPLETED:20070501 without explicit VALUE=DATE parameter.""" + cal = Calendar.from_ical( + """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""" + ) + todo = cal.todos[0] + expected = tzp.localize_utc(datetime(2007, 5, 1, 0, 0)) + assert todo.COMPLETED == expected + assert todo.completed == expected + + +def test_todo_completed_from_date_example_2(): + """Example 2: COMPLETED;VALUE=DATE:20070501 with VALUE=DATE parameter.""" + cal = Calendar.from_ical( + """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""" + ) + todo = cal.todos[0] + expected = tzp.localize_utc(datetime(2007, 5, 1, 0, 0)) + assert todo.COMPLETED == expected + assert todo.completed == expected + + +def test_todo_completed_fixture_date(todos): + """Load test file from todos fixture and verify COMPLETED date converted to UTC datetime.""" + todo = todos.issue_1797_completed_date + expected = tzp.localize_utc(datetime(2007, 5, 1, 0, 0)) + assert todo.COMPLETED == expected + assert todo.completed == expected + + +def test_todo_completed_fixture_datetime(todos): + """Load test file from todos fixture and verify COMPLETED datetime.""" + todo = todos.issue_1797_completed_datetime + expected = tzp.localize_utc(datetime(2007, 5, 1, 12, 30)) + assert todo.COMPLETED == expected + assert todo.completed == expected + + +def test_todo_completed_getter_setter_deleter(): + """Test getting, setting, and deleting COMPLETED and completed.""" + todo = Todo() + assert todo.COMPLETED is None + assert todo.completed is None + + # Set using uppercase COMPLETED with datetime + completed_dt = datetime(2024, 6, 1, 15, 0, tzinfo=UTC) + todo.COMPLETED = completed_dt + assert todo.COMPLETED == completed_dt + assert todo.completed == completed_dt + assert b"COMPLETED:20240601T150000Z" in todo.to_ical() + + # Delete using uppercase COMPLETED + del todo.COMPLETED + assert todo.COMPLETED is None + assert todo.completed is None + assert "COMPLETED" not in todo + + # Set using lowercase completed with date + completed_date = date(2024, 6, 1) + todo.completed = completed_date + assert todo.COMPLETED == tzp.localize_utc(datetime(2024, 6, 1, 0, 0)) + assert todo.completed == tzp.localize_utc(datetime(2024, 6, 1, 0, 0)) + + # Set to None clears it + todo.completed = None + assert todo.COMPLETED is None + assert todo.completed is None + + # Delete using lowercase completed + todo.completed = completed_dt + del todo.completed + assert todo.COMPLETED is None + assert todo.completed is None + + +def test_todo_new_with_completed(): + """Test creating a Todo using Todo.new(completed=...).""" + completed_dt = datetime(2024, 7, 10, 10, 0, tzinfo=UTC) + todo = Todo.new( + summary="Finish documentation", + completed=completed_dt, + ) + assert todo.COMPLETED == completed_dt + assert todo.completed == completed_dt + assert b"COMPLETED:20240710T100000Z" in todo.to_ical() + + +def test_completed_not_present_in_other_components(): + """RFC 5545 defines COMPLETED specifically for VTODO (Section 3.8.2.1).""" + event = Event() + journal = Journal() + assert not hasattr(event, "COMPLETED") + assert not hasattr(event, "completed") + assert not hasattr(journal, "COMPLETED") + assert not hasattr(journal, "completed") diff --git a/src/icalendar/tests/todos/issue_1797_completed_date.ics b/src/icalendar/tests/todos/issue_1797_completed_date.ics new file mode 100644 index 000000000..eb68b7592 --- /dev/null +++ b/src/icalendar/tests/todos/issue_1797_completed_date.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/issue_1797_completed_datetime.ics b/src/icalendar/tests/todos/issue_1797_completed_datetime.ics new file mode 100644 index 000000000..dd4d920b5 --- /dev/null +++ b/src/icalendar/tests/todos/issue_1797_completed_datetime.ics @@ -0,0 +1,9 @@ +BEGIN:VTODO +UID:20070313T123432Z-456553@example.com +DTSTAMP:20070313T123432Z +COMPLETED:20070501T123000Z +SUMMARY:Submit Quebec Income Tax Return for 2006 +CLASS:CONFIDENTIAL +CATEGORIES:FAMILY,FINANCE +STATUS:NEEDS-ACTION +END:VTODO