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-todo-completed.feature
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added :attr:`COMPLETED <icalendar.cal.todo.Todo.COMPLETED>` and :attr:`completed <icalendar.cal.todo.Todo.completed>` to access the :rfc:`5545#section-3.8.2.1` ``COMPLETED`` property of :class:`~icalendar.cal.todo.Todo`. @RishabhIIITD
47 changes: 47 additions & 0 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 @@ -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."""
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
133 changes: 133 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,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")
9 changes: 9 additions & 0 deletions src/icalendar/tests/todos/issue_1797_completed_date.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
9 changes: 9 additions & 0 deletions src/icalendar/tests/todos/issue_1797_completed_datetime.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:20070501T123000Z
SUMMARY:Submit Quebec Income Tax Return for 2006
CLASS:CONFIDENTIAL
CATEGORIES:FAMILY,FINANCE
STATUS:NEEDS-ACTION
END:VTODO