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
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,13 @@ and I do try to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.h
### Added

* `plann interactive check-pinned` goes through the past week's events pinning tasks to the calendar (as made by the panic planning in `interactive manage-tasks`) and asks if each task was done. A done task is completed (with its subtasks), and its event is marked as confirmed; its other pins may be cancelled. If not done, the event is cancelled. It is also run first in `interactive manage-tasks`. https://github.com/pycalendar/plann/pull/89
* `select --priority` selects by priority: one number, a range or a list, like `--priority 5`, `--priority 1-3` or `--priority 1,5-9`. 0 matches tasks with no priority set. The filtering is done client-side, and needs icalendar-searcher 1.4.0 or later.

### Fixed

* Postponing (`edit --postpone`, `interactive manage-tasks`) left DTSTART behind on a task where DTSTART equals DUE, or where one of them is a date and the other a timestamp, so the duration (used as a time estimate) grew with every postponement. DTSTART now moves along with DUE, keeping the duration.
* `interactive manage-tasks`: a parent task postponed together with its child could be postponed once more in its own turn, and with caldav 3.6 this crashed with a "412 Precondition Failed" error. It is now skipped, with a note. A task changed on the server in the meantime is reloaded before it is postponed.
* `select` no longer crashes with `KeyError: 'DTEND'` on a task where one of the start and due times is a date and the other a timestamp. The date is now turned into a timestamp at midnight; before, a timestamp could also lose its time of day.
* `interactive manage-tasks` no longer stops with a traceback when the server refuses to store a task it postpones, e.g. with "423 Locked" from a Xandikos server busy with another write. The task is reported and the rest are still postponed.

## v1.3.0 - 2026-10-23
Expand Down
2 changes: 1 addition & 1 deletion TASK_MANAGEMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -345,7 +345,7 @@ To interactively find and set the missing properties, it's possible to do `plann

### Listing tasks

The `select`-command can be used to list tasks. The `--todo`-flag will ensure that only pending tasks are listed. Say that it's a nice day for garden work, then `plann select --todo --category garden list` would probably be the right thing to do.
The `select`-command can be used to list tasks. The `--todo`-flag will ensure that only pending tasks are listed. Say that it's a nice day for garden work, then `plann select --todo --category garden list` would probably be the right thing to do. `--priority` selects by priority, like `plann select --todo --priority 1-3 list` for the most important tasks (`--priority 0` gives the tasks with no priority set).

There exists some other ways too. `plann agenda` will list out events and tasks with `DTSTART` in the near-term future. `plann interactive check-due` will go through overdue and near-due tasks and interactively ask the user what to do with them. Then there is also the "panic planning mode" available, for instance `plann interactive dismiss-panic` - it will list overdue tasks and tasks that you probably won't have time to do within the planned `DUE`. More on that below.

Expand Down
1 change: 1 addition & 0 deletions plann/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,7 @@ def freebusy_sync(ctx, to_section, summary, tag, days, hours, weekdays_only, dry
@click.option('--offset', help='Skip the first objects', type=int)
@click.option('--freebusyhack', help='DEPRECATED, use the freebusy-sync command. Removes almost everything from the ical and replaces the summary with the provided string. Leaks the details of recurrence exceptions.')
@click.option('--pinned-tasks/--no-pinned-tasks', default=None, help='select all/no pinned tasks')
@click.option('--priority', help='select by priority: a number, a range or a list, like 5, 1-3 or 1,5-9. 1 is the highest priority, 9 the lowest, 0 undefined (also matches tasks without a priority)')
@click.pass_context
def select(*largs, **kwargs):
"""Search command, allows listing, editing, etc
Expand Down
45 changes: 39 additions & 6 deletions plann/commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
_component_type,
_is_comma_list_attr,
_list,
_normalize_start_end,
_process_set_arg,
_procrastinate,
_RelativeCache,
Expand Down Expand Up @@ -94,7 +95,28 @@ def fkey(obj):
return obj.icalendar_component.get(skey)
return reverse, fkey

def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=None, warn_on_missing_uid=True, sort_key=[], skip_parents=None, skip_children=None, limit=None, offset=None, freebusyhack=None, pinned_tasks=None, **kwargs_):
def _parse_priority(spec):
"""The priorities in ``spec``: a comma-separated list of numbers or
ranges, like ``5``, ``1-3`` or ``1,5-9``."""
wanted = set()
for part in spec.split(','):
rx = re.fullmatch(r'\s*(\d)\s*(?:-\s*(\d)\s*)?', part)
if not rx:
raise click.BadParameter(f"expected priorities 0-9 like 5, 1-3 or 1,5-9, got {spec!r}", param_hint='--priority')
lo, hi = sorted((int(rx.group(1)), int(rx.group(rx.lastindex))))
wanted.update(range(lo, hi + 1))
return wanted

def _filter_priority(objs, wanted):
"""Keep the objects with a PRIORITY in ``wanted``. 0 is RFC 5545
"undefined priority" and also matches a missing PRIORITY. Done
client-side, as CalDAV searches have no integer comparison."""
searcher = Searcher()
searcher.add_property_filter('PRIORITY', wanted, operator='in')
return [obj for obj in objs
if searcher.check_component(obj) or (0 in wanted and 'PRIORITY' not in obj.icalendar_component)]

def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=None, warn_on_missing_uid=True, sort_key=[], skip_parents=None, skip_children=None, limit=None, offset=None, freebusyhack=None, pinned_tasks=None, priority=None, **kwargs_):
"""
select/search/filter tasks/events, for listing/editing/deleting, etc
"""
Expand Down Expand Up @@ -147,6 +169,10 @@ def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=N
if uid:
return

## parsed before searching, so a typo costs no server round-trip
if priority is not None:
priority = _parse_priority(priority)

if pinned_tasks:
kwargs['event'] = True
kwargs['todo'] = None
Expand All @@ -173,8 +199,14 @@ def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=N

if 'start' in kwargs and 'end' in kwargs:
kwargs['expand'] = True
found = []
for c in ctx.obj['calendars']:
objs.extend(c.search(**kwargs))
found.extend(c.search(**kwargs))
## with --pinned-tasks the search finds the pinning events, and the
## priority filter waits for the tasks they pin, below
if priority is not None and pinned_tasks is None:
found = _filter_priority(found, priority)
objs.extend(found)

if skip_children or skip_parents:
i = 0
Expand Down Expand Up @@ -204,6 +236,8 @@ def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=N
children = _relships_by_type(obj, 'CHILD').get('CHILD',[])
if not any(x.icalendar_component.get('STATUS', '')!='CANCELLED' for x in children if isinstance(x, caldav.Event)):
ret_objs.append(obj)
if priority is not None:
ret_objs = _filter_priority(ret_objs, priority)
ctx.obj['objs'] = ret_objs

## OPTIMIZE TODO: sorting the list multiple times rather than once is a bit of brute force, if there are several sort keys and long list of objects, we should sort once and consider all sort keys while sorting
Expand All @@ -222,11 +256,10 @@ def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=N
for obj in ctx.obj['objs']:
comp = obj.icalendar_component
dtstart = comp.get('dtstart')
dtend = comp.get('dtend') or comp.get('due')
if dtstart and dtend and isinstance(dtstart.dt, datetime.datetime) != isinstance(dtend.dt, datetime.datetime):
endkey = 'DTEND' if 'DTEND' in comp else 'DUE'
dtend = comp.get(endkey)
if _normalize_start_end(comp):
logging.error(f"task with uuid {comp['uid']} has non-matching types on dtstart and dtend/due, setting both to timestamps")
comp['dtstart'].dt = datetime.datetime(dtstart.dt.year, dtstart.dt.month, dtstart.dt.day)
comp['dtend'].dt = datetime.datetime(dtend.dt.year, dtend.dt.month, dtend.dt.day)
elif dtstart and dtend and dtstart.dt > dtend.dt:
logging.error(f"task with uuid {comp['uid']} as dtstart after dtend/due")

Expand Down
27 changes: 27 additions & 0 deletions plann/lib.py
Original file line number Diff line number Diff line change
Expand Up @@ -299,6 +299,25 @@ def _summary(obj):
i = _icalendar_component(obj)
return i.get('summary') or i.get('description') or i.get('uid')

def _normalize_start_end(comp):
"""DTSTART and DTEND/DUE of mixed types (date and timestamp) makes
durations meaningless. Only the date-valued one is converted, to
midnight in the timezone of the other, which keeps its time.
Returns True if something was changed."""
dtstart = comp.get('DTSTART')
endkey = 'DTEND' if 'DTEND' in comp else 'DUE'
dtend = comp.get(endkey)
if not (dtstart and dtend) or isinstance(dtstart.dt, datetime.datetime) == isinstance(dtend.dt, datetime.datetime):
return False
tzinfo = next(comp[key].dt.tzinfo for key in ('DTSTART', endkey)
if isinstance(comp[key].dt, datetime.datetime))
for key in ('DTSTART', endkey):
dt = comp[key].dt
if not isinstance(dt, datetime.datetime):
comp.pop(key)
comp.add(key, datetime.datetime(dt.year, dt.month, dt.day, tzinfo=tzinfo))
return True

childlike = {'CHILD', 'NEXT', 'FINISHTOSTART'}
parentlike = {'PARENT', 'FIRST', 'DEPENDS-ON', 'STARTTOFINISH'}

Expand Down Expand Up @@ -357,7 +376,15 @@ def _procrastinate(objs, delay, check_dependent="error", with_children=False, wi
## Let's force the due to be a timestamp
if not isinstance(new_due, datetime.datetime):
new_due = datetime.datetime(new_due.year, new_due.month, new_due.day)
comp = x.icalendar_component
_normalize_start_end(comp)
## caldav leaves DTSTART alone if the duration is zero
zero_duration = 'DTSTART' in comp and any(k in comp for k in ('DUE', 'DTEND', 'DURATION')) and x.get_duration() == datetime.timedelta(0)
parent = x.set_due(new_due, move_dtstart=True, check_dependent=chk_parent)
if zero_duration and not parent:
comp.pop('DTSTART')
## set_due may have converted a naive new_due, DTSTART must match DUE
comp.add('DTSTART', comp['DUE'].dt)
if parent:
if check_dependent in ("error", "interactive"):
i = x.icalendar_component
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ dependencies = [
"dateparser>=1.2",
"python-dateutil",
"icalendar>=7.0.0",
"icalendar_searcher",
"icalendar_searcher>=1.4.0",
]

[project.urls]
Expand Down
166 changes: 166 additions & 0 deletions tests/test_commands.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
from unittest.mock import MagicMock, patch # noqa: F401

import click
from caldav import Todo


Expand All @@ -23,3 +24,168 @@ def _todo(uid, extra):
missing = _todos_missing([absent, zero, real], 'priority')
uids = {x.icalendar_component['UID'] for x in missing}
assert uids == {'no-priority', 'zero-priority'}


def _prio_todo(uid, priority=None):
extra = f"PRIORITY:{priority}\n" if priority is not None else ""
return Todo(data=(
"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VTODO\n"
f"UID:{uid}\nSUMMARY:{uid}\n{extra}END:VTODO\nEND:VCALENDAR"))


def test_select_by_priority():
"""`select --priority` filters client-side: CalDAV has no integer
comparison, so the server cannot do it. 0 means undefined, matching
a missing PRIORITY as well; ranges and lists are accepted."""
import pytest

from plann.commands import _filter_priority, _parse_priority

objs = [_prio_todo('absent'), _prio_todo('zero', 0), _prio_todo('one', 1),
_prio_todo('three', 3), _prio_todo('five', 5), _prio_todo('nine', 9)]

def uids(spec):
return {x.icalendar_component['UID'] for x in _filter_priority(objs, _parse_priority(spec))}

assert uids('5') == {'five'}
assert uids('0') == {'absent', 'zero'}
assert uids('1-3') == {'one', 'three'}
assert uids('3-1') == {'one', 'three'}
assert uids('1,5-9') == {'one', 'five', 'nine'}
with pytest.raises(click.BadParameter):
uids('high')
with pytest.raises(click.BadParameter):
uids('10')


def test_select_passes_priority_filter_not_to_server():
"""--priority must not reach caldav's search (it would become a text
match there), but must filter the search result."""
from plann.commands import _select

cal = MagicMock()
cal.search.return_value = [_prio_todo('one', 1), _prio_todo('five', 5)]
ctx = MagicMock()
ctx.obj = {'calendars': [cal]}
_select(ctx, todo=True, priority='5')
assert 'priority' not in cal.search.call_args.kwargs
assert [x.icalendar_component['UID'] for x in ctx.obj['objs']] == ['five']


def test_select_fixes_mixed_date_types_on_todo_with_due():
"""A task with a date DTSTART and a timestamp DUE (or vice versa) is
normalised to timestamps. Tasks have DUE, not DTEND, so the fix-up
must touch whichever of the two is there."""
import datetime

from plann.commands import _select

todo = Todo(data=(
"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VTODO\nUID:mixed\nSUMMARY:mixed\n"
"DTSTART;VALUE=DATE:20261101\nDUE:20261110T120000\n"
"END:VTODO\nEND:VCALENDAR"))
cal = MagicMock()
cal.search.return_value = [todo]
ctx = MagicMock()
ctx.obj = {'calendars': [cal]}
_select(ctx, todo=True)
comp = ctx.obj['objs'][0].icalendar_component
assert 'DTEND' not in comp
assert isinstance(comp['DTSTART'].dt, datetime.datetime)
assert comp['DTSTART'].dt == datetime.datetime(2026, 11, 1)
assert comp['DUE'].dt == datetime.datetime(2026, 11, 10, 12)
assert b'VALUE=DATE' not in comp.to_ical()


def test_select_fixes_mixed_date_types_keeping_the_timezone():
"""The date becomes midnight in the timezone of the timestamp, or
the two cannot be compared (postponing then crashes in caldav)."""
import datetime

from plann.commands import _select

todo = Todo(data=(
"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VTODO\nUID:mixed\nSUMMARY:mixed\n"
"DTSTART;VALUE=DATE:20261101\nDUE:20261110T120000Z\n"
"END:VTODO\nEND:VCALENDAR"))
cal = MagicMock()
cal.search.return_value = [todo]
ctx = MagicMock()
ctx.obj = {'calendars': [cal]}
_select(ctx, todo=True)
comp = ctx.obj['objs'][0].icalendar_component
assert comp['DUE'].dt - comp['DTSTART'].dt == datetime.timedelta(days=9, hours=12)


def test_select_priority_with_pinned_tasks_filters_the_tasks():
"""--pinned-tasks --todo searches the pinning events and returns their
parent tasks; --priority is about the tasks, not the events."""
from caldav import Event

from plann.commands import _select

event = Event(data=(
"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nUID:pin\n"
"DTSTART:20261113T100000Z\nDTEND:20261113T110000Z\n"
"END:VEVENT\nEND:VCALENDAR"))
cal = MagicMock()
cal.search.return_value = [event]
ctx = MagicMock()
ctx.obj = {'calendars': [cal]}
parents = [_prio_todo('one', 1), _prio_todo('five', 5)]
with patch('plann.commands._pinned_task_parents', return_value=parents):
_select(ctx, todo=True, pinned_tasks=True, priority='5')
assert [x.icalendar_component['UID'] for x in ctx.obj['objs']] == ['five']


def test_select_rejects_bad_priority_before_searching():
import pytest

from plann.commands import _select

cal = MagicMock()
ctx = MagicMock()
ctx.obj = {'calendars': [cal]}
with pytest.raises(click.BadParameter):
_select(ctx, todo=True, priority='high')
cal.search.assert_not_called()


def _fix_up(component, lines):
from caldav import Event

from plann.commands import _select

cls = Event if component == 'VEVENT' else Todo
obj = cls(data=(
f"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:{component}\nUID:mixed\nSUMMARY:mixed\n"
f"{lines}END:{component}\nEND:VCALENDAR"))
cal = MagicMock()
cal.search.return_value = [obj]
ctx = MagicMock()
ctx.obj = {'calendars': [cal]}
_select(ctx)
return ctx.obj['objs'][0].icalendar_component


def test_select_fixes_mixed_date_types_timestamp_start_date_due():
import datetime

comp = _fix_up('VTODO', "DTSTART:20261101T090000\nDUE;VALUE=DATE:20261110\n")
assert comp['DTSTART'].dt == datetime.datetime(2026, 11, 1, 9)
assert comp['DUE'].dt == datetime.datetime(2026, 11, 10)


def test_select_fixes_mixed_date_types_on_event():
import datetime

comp = _fix_up('VEVENT', "DTSTART;VALUE=DATE:20261101\nDTEND:20261101T120000\n")
assert 'DUE' not in comp
assert comp['DTSTART'].dt == datetime.datetime(2026, 11, 1)
assert comp['DTEND'].dt == datetime.datetime(2026, 11, 1, 12)


def test_select_fixes_mixed_date_types_with_tzid():
"""The converted property gets the TZID of the other one."""
comp = _fix_up('VTODO', "DTSTART;VALUE=DATE:20261101\nDUE;TZID=Europe/Oslo:20261110T120000\n")
assert b'DTSTART;TZID=Europe/Oslo:20261101T000000' in comp.to_ical()
43 changes: 43 additions & 0 deletions tests/test_lib.py
Original file line number Diff line number Diff line change
Expand Up @@ -959,3 +959,46 @@ def test_list_json_one_vtimezone_per_tzid():
_list([_event_in_oslo('a'), _event_in_oslo('b')], as_json=True)
names = [comp[0] for comp in json.loads(echo.call_args.args[0])[2]]
assert names == ['vtimezone', 'vevent', 'vevent']

def _todo_with(dtstart_line, end_line):
t = Todo()
t.data = ("BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:x\nBEGIN:VTODO\nUID:a\nDTSTAMP:20261101T000000Z\n"
f"SUMMARY:x\n{dtstart_line}\n{end_line}\nEND:VTODO\nEND:VCALENDAR\n")
return t

@pytest.mark.parametrize("dtstart_line,end_line,hours", [
## date-valued DTSTART on the same day as a timestamp DUE
("DTSTART;VALUE=DATE:20261101", "DUE:20261101T120000Z", 12),
("DTSTART;VALUE=DATE:20261101", "DUE:20261102T120000Z", 36),
## DTSTART == DUE
("DTSTART:20261101T120000Z", "DUE:20261101T120000Z", 0),
("DTSTART:20261101T100000Z", "DUE:20261101T120000Z", 2),
])
def test_procrastinate_moves_dtstart(dtstart_line, end_line, hours):
_check_moves_dtstart(dtstart_line, end_line, hours, '14d')

def test_procrastinate_zero_duration_to_absolute_date():
"""a naive postpone target must not leave DTSTART floating next to a UTC DUE"""
t = _todo_with("DTSTART:20261101T120000Z", "DUE:20261101T120000Z")
with patch.object(t, 'save'):
_procrastinate([t], '2027-01-05')
comp = t.icalendar_component
assert comp['DTSTART'].dt == comp['DUE'].dt
assert t.get_duration() == timedelta(0)

def test_procrastinate_dtstart_only_left_alone():
t = _todo_with("DTSTART:20261101T120000Z", "SUMMARY:y")
with patch.object(t, 'save'):
_procrastinate([t], '14d')
assert t.icalendar_component['DTSTART'].dt == datetime(2026, 11, 1, 12, tzinfo=timezone.utc)

def _check_moves_dtstart(dtstart_line, end_line, hours, delay):
"""DTSTART moves along with DUE, keeping the duration (which is
used as a time estimate), also when the duration is zero or the
DTSTART is a date and the DUE a timestamp"""
t = _todo_with(dtstart_line, end_line)
with patch.object(t, 'save'):
_procrastinate([t], delay)
comp = t.icalendar_component
assert comp['DUE'].dt - comp['DTSTART'].dt == timedelta(hours=hours)
assert comp['DTSTART'].dt > datetime.now(timezone.utc)
Loading