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

* `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

### Changed

* The `plann interactive` subcommands now have the same defaults as when `interactive manage-tasks` runs them, except `dismiss-panic --hours-per-day`, which `manage-tasks` runs with 24 and then 14. `check-due` looks 24 hours ahead (was 16) and goes through at most 16 tasks (was unlimited); `split-huge-tasks` and `split-high-pri-tasks` look 60 days and 640 tasks ahead (was 30 days and 32 tasks).

### Fixed

* A task with DTSTART as a date and DUE as a timestamp (or the other way around) made `interactive manage-tasks` and other selections crash with `KeyError: 'DTEND'`. The date is now made a timestamp at local midnight; the time of day on the other one is kept (it used to be dropped), and the result is valid iCalendar.
* `interactive check-due` (also run by `interactive manage-tasks`) silently left out the due tasks beyond the first 16, usually the low-priority ones. It now says how many tasks are due when it cannot show them all.
* A bare hour (one or two digits, 0-23) in a date or time argument, like `--set-dtstart=14`, means 14:00 today in the implicit timezone. It was taken as the 14th of the month, giving an all-day task.
* `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.
* `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.

Expand Down
30 changes: 19 additions & 11 deletions plann/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
## `from plann import ...`

import datetime
import inspect
import logging
import sys

Expand Down Expand Up @@ -68,6 +69,13 @@

list_type = list


def _default(func, param):
"""The default value of a parameter of func - lets a click option
share its default with the implementation, which `manage-tasks`
calls directly"""
return inspect.signature(func).parameters[param].default

## TODO:

## should make some subclasses of click.ParamType:
Expand Down Expand Up @@ -706,8 +714,8 @@ def manage_tasks(ctx):
_agenda(ctx)

@interactive.command()
@click.option('--limit', type=int, help='If more than limit overdue tasks are found, probably we should do a mass procrastination rather than going through one and one task')
@click.option('--lookahead', help='Look-ahead time - check tasks that needs to be completed in the near future', default='+16h')
@click.option('--limit', type=int, help='If more than limit overdue tasks are found, probably we should do a mass procrastination rather than going through one and one task', default=_default(_check_due, 'limit'))
@click.option('--lookahead', help='Look-ahead time - check tasks that needs to be completed in the near future', default=_default(_check_due, 'lookahead'))
@click.pass_context
def check_due(ctx, limit, lookahead):
"""
Expand All @@ -716,7 +724,7 @@ def check_due(ctx, limit, lookahead):
return _check_due(ctx, limit, lookahead)

@interactive.command()
@click.option('--lookback', help='how far back to look for events pinning tasks to the calendar', default='7d')
@click.option('--lookback', help='how far back to look for events pinning tasks to the calendar', default=_default(_check_pinned, 'lookback'))
@click.pass_context
def check_pinned(ctx, lookback):
"""
Expand All @@ -729,9 +737,9 @@ def check_pinned(ctx, lookback):

@interactive.command()
@click.option('--hours-per-day', help='how many hours per day you expect to be able to dedicate to those tasks/events', default=4)
@click.option('--lookahead', help='timespan to investigate', default='60d')
@click.option('--lookahead', help='timespan to investigate', default=_default(_dismiss_panic, 'lookahead'))
@click.pass_context
def dismiss_panic(ctx, hours_per_day, lookahead='60d'):
def dismiss_panic(ctx, hours_per_day, lookahead):
"""Checks workload, procrastinates tasks

Search for panic points, checks if they can be solved by
Expand All @@ -741,9 +749,9 @@ def dismiss_panic(ctx, hours_per_day, lookahead='60d'):


@interactive.command()
@click.option('--threshold', help='tasks with a higher estimate than this should be split into subtasks', default='4h')
@click.option('--max-lookahead', help='ignore tasks further in the future than this', default='30d')
@click.option('--limit-lookahead', help='only consider the first x tasks', default=32)
@click.option('--threshold', help='tasks with a higher estimate than this should be split into subtasks', default=_default(_split_huge_tasks, 'threshold'))
@click.option('--max-lookahead', help='ignore tasks further in the future than this', default=_default(_split_huge_tasks, 'max_lookahead'))
@click.option('--limit-lookahead', help='only consider the first x tasks', default=_default(_split_huge_tasks, 'limit_lookahead'))
@click.pass_context
def split_huge_tasks(ctx, threshold, max_lookahead, limit_lookahead):
"""
Expand All @@ -752,9 +760,9 @@ def split_huge_tasks(ctx, threshold, max_lookahead, limit_lookahead):
return _split_huge_tasks(ctx, threshold, max_lookahead, limit_lookahead)

@interactive.command()
@click.option('--max-lookahead', help='ignore tasks further in the future than this', default='30d')
@click.option('--threshold', help='tasks with this or lower priority should always have children', default=2)
@click.option('--limit-lookahead', help='only consider the first x tasks', default=32)
@click.option('--max-lookahead', help='ignore tasks further in the future than this', default=_default(_split_high_pri_tasks, 'max_lookahead'))
@click.option('--threshold', help='tasks with this or lower priority should always have children', default=_default(_split_high_pri_tasks, 'threshold'))
@click.option('--limit-lookahead', help='only consider the first x tasks', default=_default(_split_high_pri_tasks, 'limit_lookahead'))
@click.pass_context
def split_high_pri_tasks(ctx, threshold, max_lookahead, limit_lookahead):
"""Tasks with very high priority (1,2) indicates a hard DUE that
Expand Down
52 changes: 35 additions & 17 deletions plann/commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -220,15 +220,7 @@ def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=N

## some sanity checks
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):
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")
_fix_mismatched_date_types(obj.icalendar_component)

## I need a way to copy time information from one calendar to another
## (typically between private and work calendars) without carrying over
Expand All @@ -244,6 +236,30 @@ def __select(ctx, extend_objects=False, all=None, uid=[], abort_on_missing_uid=N
if attr == 'SUMMARY':
comp[attr] = freebusyhack

def _fix_mismatched_date_types(comp):
"""If one of DTSTART and DTEND/DUE is a date and the other a timestamp,
turn the date into a timestamp at midnight in the implicit timezone
(floating, if the timestamp is floating), so they can be compared. The
time of day on the timestamp is kept. Logs an error if DTSTART comes
after DTEND/DUE."""
endkey = 'DTEND' if 'DTEND' in comp else 'DUE'
dtstart = comp.get('DTSTART')
dtend = comp.get(endkey)
if not (dtstart and dtend):
return
start_is_ts = isinstance(dtstart.dt, datetime.datetime)
if start_is_ts != isinstance(dtend.dt, datetime.datetime):
logging.error(f"task with uuid {comp['uid']} has non-matching types on dtstart and dtend/due, setting both to timestamps")
date_key, d, other = (endkey, dtend.dt, dtstart.dt) if start_is_ts else ('DTSTART', dtstart.dt, dtend.dt)
new_ts = datetime.datetime(d.year, d.month, d.day)
if other.tzinfo:
new_ts = _ensure_ts(d)
## replace the property rather than setting .dt, so VALUE=DATE goes away
comp.pop(date_key)
comp.add(date_key, new_ts)
elif _ensure_ts(dtstart.dt) > _ensure_ts(dtend.dt):
logging.error(f"task with uuid {comp['uid']} as dtstart after dtend/due")

def _categories_in_use(objs):
categories = set()
for obj in objs:
Expand Down Expand Up @@ -490,17 +506,19 @@ def _agenda(ctx):

def _check_due(ctx, limit=16, lookahead='24h'):
end_ = parse_add_dur(datetime.datetime.now(), lookahead)
_select(ctx=ctx, todo=True, end=end_, limit=limit, sort_key=['{PRIORITY:?0?} {DTSTART:?{DUE:?(0000)?}?%F %H:%M:%S}'])
objs = ctx.obj['objs']
for obj in objs:
_select(ctx=ctx, todo=True, end=end_, sort_key=['{PRIORITY:?0?} {DTSTART:?{DUE:?(0000)?}?%F %H:%M:%S}'])
def is_due(obj):
## client side filtering in case the server returns too much
## TODO: should be moved to the caldav library
## TODO: consider the limit ... we may risk that nothing comes up due to the limit above
comp = obj.icalendar_component
dtstart = comp.get('dtstart') or comp.get('due')
dtstart = _ensure_ts(dtstart)
if dtstart.strftime("%F%H%M") > end_.strftime("%F%H%M"):
continue
dtstart = _ensure_ts(comp.get('dtstart') or comp.get('due'))
return dtstart.strftime("%F%H%M") <= end_.strftime("%F%H%M")
objs = [obj for obj in ctx.obj['objs'] if is_due(obj)]
if limit is not None and len(objs) > limit:
click.echo(f"{len(objs)} tasks are due, only the first {limit} are shown here. "
"Consider postponing many at once with `plann interactive dismiss-panic`.")
objs = objs[:limit]
for obj in objs:
_interactive_edit(obj)

def _pinned_task_parents(event):
Expand Down
5 changes: 5 additions & 0 deletions plann/timespec.py
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,11 @@ def _parse_dt(input, return_type=None):
return input
if input == 'now':
ret = _now()
elif input.isdigit() and len(input) <= 2 and int(input) < 24:
## a bare hour, i.e. `--set-dtstart=14` means 14:00 today.
## dateparser would take it as a day of the month.
ret = _now().replace(hour=int(input), minute=0, second=0, microsecond=0)
return ret.date() if return_type is datetime.date else ret
elif input.startswith('+'):
ret = parse_add_dur(_now(), input[1:])
else:
Expand Down
47 changes: 47 additions & 0 deletions tests/test_commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,50 @@ 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 _vtodo(uid, extra):
return Todo(data=(
"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VTODO\n"
f"UID:{uid}\nSUMMARY:{uid}\n{extra}END:VTODO\nEND:VCALENDAR"))


def test_mismatched_date_types_fixed_on_due(monkeypatch):
"""A VTODO with DTSTART as a date and DUE as a timestamp has no DTEND.
The sanity check must fix DUE, not crash with KeyError on DTEND - and
must keep the time of day already on DUE. The date becomes local
midnight in the implicit timezone, also when DUE is in UTC."""
import datetime
from zoneinfo import ZoneInfo

from plann import timespec
from plann.commands import _fix_mismatched_date_types

monkeypatch.setitem(vars(timespec.tz), "_implicit_timezone", ZoneInfo("America/New_York"))
comp = _vtodo('mixed', "DTSTART;VALUE=DATE:20261116\nDUE:20261118T140000Z\n").icalendar_component
_fix_mismatched_date_types(comp)
assert 'DTEND' not in comp
assert comp['DTSTART'].dt == datetime.datetime(2026, 11, 16, tzinfo=ZoneInfo("America/New_York"))
assert comp['DTSTART'].dt.date() == datetime.date(2026, 11, 16)
assert comp['DUE'].dt == datetime.datetime(2026, 11, 18, 14, 0, tzinfo=datetime.timezone.utc)
assert b'VALUE=DATE' not in comp.to_ical()


def test_mismatched_date_types_floating_stays_floating():
"""With a floating timestamp on the other side, the date becomes a
floating midnight too"""
import datetime

from plann.commands import _fix_mismatched_date_types

comp = _vtodo('floating', "DTSTART:20261116T100000\nDUE;VALUE=DATE:20261118\n").icalendar_component
_fix_mismatched_date_types(comp)
assert comp['DUE'].dt == datetime.datetime(2026, 11, 18)


def test_aware_vs_floating_does_not_crash():
"""A floating DTSTART and a UTC DUE cannot be compared directly"""
from plann.commands import _fix_mismatched_date_types

comp = _vtodo('aware-floating', "DTSTART:20261119T100000\nDUE:20261118T140000Z\n").icalendar_component
_fix_mismatched_date_types(comp)
54 changes: 54 additions & 0 deletions tests/test_plann_cli.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
## Check https://click.palletsprojects.com/en/8.1.x/testing/

import inspect
from datetime import datetime, timedelta
from unittest.mock import patch

import caldav
import pytest
from caldav import Todo
from click.testing import CliRunner

Expand All @@ -14,6 +16,32 @@
from tests.test_freebusy import FakeCalendar, _event, oslo


@pytest.mark.parametrize("command, function", [
('check-pinned', '_check_pinned'),
('check-due', '_check_due'),
('dismiss-panic', '_dismiss_panic'),
('split-huge-tasks', '_split_huge_tasks'),
('split-high-pri-tasks', '_split_high_pri_tasks'),
])
def test_interactive_cli_defaults_match_manage_tasks(command, function):
"""`plann interactive X` and `manage-tasks` (which calls the
underlying function with its defaults) should behave the same"""
signature = inspect.signature(getattr(commands_mod, function))
calls = []
with patch.object(cli_mod, function, lambda *a: calls.append(signature.bind(*a).arguments)), \
patch.object(cli_mod, '_discover_calendars', lambda kwargs: []):
res = CliRunner().invoke(cli, ['interactive', command])
assert res.exit_code == 0, res.output
[args] = calls
for name, param in signature.parameters.items():
if param.default is not inspect.Parameter.empty:
assert args[name] == param.default, name


def test_check_due_looks_24h_ahead():
assert inspect.signature(commands_mod._check_due).parameters['lookahead'].default == '24h'


def _make_todo(uid, *, category=False, due=False, priority=False, dtstart=False):
lines = ["UID:" + uid, "SUMMARY:task " + uid, "STATUS:NEEDS-ACTION"]
if category:
Expand All @@ -37,6 +65,32 @@ def __init__(self):
self.obj = {'calendars': [], 'objs': []}


def _check_due_with(todos, limit):
"""run _check_due over the given todos, return the ones it asks about"""
def select(ctx, **kwargs):
assert 'limit' not in kwargs, "the limit should apply after the client side filtering"
ctx.obj['objs'] = list(todos)
asked = []
with patch.object(commands_mod, '_select', select), \
patch.object(commands_mod, '_interactive_edit', asked.append):
commands_mod._check_due(_FakeCtx(), limit=limit)
return asked


def test_check_due_warns_when_tasks_are_left_out(capsys):
todos = [_make_todo(f"t{i}", due=True, dtstart=True) for i in range(5)]
assert _check_due_with(todos, limit=3) == todos[:3]
out = capsys.readouterr().out
assert '5 tasks are due' in out
assert 'dismiss-panic' in out


def test_check_due_no_warning_within_limit(capsys):
todos = [_make_todo(f"t{i}", due=True, dtstart=True) for i in range(3)]
assert _check_due_with(todos, limit=3) == todos
assert capsys.readouterr().out == ''


def test_todos_missing():
"""_todos_missing keeps only the tasks where the property is absent."""
with_cat = _make_todo('a', category=True)
Expand Down
20 changes: 20 additions & 0 deletions tests/test_timespec.py
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,26 @@ def test_invalid_raises(self):
with pytest.raises(ValueError):
parse_dt("not a date at all !!!!")

@pytest.mark.parametrize("hour", ["0", "9", "09", "14", "23"])
def test_bare_hour(self, hour):
"""A bare number 0-23 is an hour today in the implicit timezone,
not a day of the month (``--set-dtstart=14`` means 14:00)"""
tz.implicit_timezone = "Europe/Oslo"
result = parse_dt(hour)
assert result == datetime.now(OSLO).replace(
hour=int(hour), minute=0, second=0, microsecond=0)

def test_bare_number_with_leading_zeros_is_not_an_hour(self):
"""Only one or two digits are an hour; "0001" is something else"""
tz.implicit_timezone = "Europe/Oslo"
result = parse_dt("0001")
assert not (isinstance(result, datetime) and result.date() == datetime.now(OSLO).date() and result.hour == 1)

def test_bare_day_of_month(self):
"""Numbers that cannot be an hour are still a day of the month"""
tz.implicit_timezone = "Europe/Oslo"
assert parse_dt("28").day == 28


class TestDurationGrammar:
"""The [smhdwy] relative-duration grammar is centralised in timespec.py."""
Expand Down
Loading