diff --git a/news/1797.feature b/news/1797.feature new file mode 100644 index 000000000..f372cbb2f --- /dev/null +++ b/news/1797.feature @@ -0,0 +1 @@ +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 64fd73c41..fae9ecf97 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, @@ -89,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 @@ -172,6 +173,32 @@ class Todo(Component): property_del_duration, property_doc_duration_template.format(component="VTODO"), ) + COMPLETED = single_utc_property( + "COMPLETED", + """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 + 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 timezone, datetime + >>> from icalendar import Todo + >>> UTC = timezone.utc + >>> todo = Todo() + >>> todo.COMPLETED = datetime(2007, 5, 1, 12, 0, tzinfo=UTC) + >>> todo.COMPLETED + datetime.datetime(2007, 5, 1, 12, 0, tzinfo=ZoneInfo(key='UTC')) + + See also: + :attr:`status` + """, + ) def _get_start_end_duration(self): """Verify the calendar validity and return the right attributes.""" @@ -356,6 +383,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 +420,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. @@ -454,6 +483,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/todo_completed.ics b/src/icalendar/tests/calendars/todo_completed.ics new file mode 100644 index 000000000..84afb0ac1 --- /dev/null +++ b/src/icalendar/tests/calendars/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: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_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 7bac13abb..9eb7fbc31 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/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