Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions news/1797.feature
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added property :attr:`Todo.COMPLETED <icalendar.cal.todo.Todo.COMPLETED>` per :rfc:`5545#section-3.8.2.1`. @RajGahoi

@SemTiOne SemTiOne Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Added property :attr:`Todo.COMPLETED <icalendar.cal.todo.Todo.COMPLETED>` per :rfc:`5545#section-3.8.2.1`. @RajGahoi
Added property :attr:`Todo.COMPLETED <icalendar.cal.todo.Todo.COMPLETED>` per :rfc:`5545#section-3.8.2.1`. :user:`RajGahoi`

34 changes: 32 additions & 2 deletions src/icalendar/cal/todo.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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."""
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions src/icalendar/tests/calendars/todo_completed.ics
Original file line number Diff line number Diff line change
@@ -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
91 changes: 91 additions & 0 deletions src/icalendar/tests/test_issue_1797_todo_completed.py
Original file line number Diff line number Diff line change
@@ -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
3 changes: 2 additions & 1 deletion src/icalendar/tests/test_property_docstrings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand All @@ -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"],
}


Expand Down
9 changes: 9 additions & 0 deletions src/icalendar/tests/todos/completed.ics
Original file line number Diff line number Diff line change
@@ -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
5 changes: 5 additions & 0 deletions src/icalendar/tests/todos/rfc5545_completed.ics
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
BEGIN:VTODO
UID:20070313T123432Z-456553@example.com
DTSTAMP:20070313T123432Z
COMPLETED:19960401T150000Z
END:VTODO
Loading