diff --git a/tests/main.sqlite b/tests/main.sqlite index 9c7e6d6..00cbf5f 100644 Binary files a/tests/main.sqlite and b/tests/main.sqlite differ diff --git a/tests/test_things.py b/tests/test_things.py index 1fa3ea7..a30404b 100644 --- a/tests/test_things.py +++ b/tests/test_things.py @@ -39,6 +39,7 @@ ) PROJECTS = 4 UPCOMING = 1 +UPCOMING_REPEATING = 1 DEADLINE_PAST = 3 DEADLINE_FUTURE = 1 DEADLINE = DEADLINE_PAST + DEADLINE_FUTURE @@ -128,7 +129,11 @@ def test_trashed(self): def test_upcoming(self): tasks = things.upcoming() - self.assertEqual(UPCOMING, len(tasks)) + self.assertEqual(UPCOMING + UPCOMING_REPEATING, len(tasks)) + self.assertEqual("2030-01-01", tasks[-1]["next_instance_start_date"]) + self.assertEqual( + UPCOMING + UPCOMING_REPEATING, things.upcoming(count_only=True) + ) def test_deadlines(self): tasks = things.tasks(deadline="past") @@ -351,6 +356,38 @@ def test_tasks(self): with self.assertRaises((sqlite3.ProgrammingError, ValueError)): things.tasks(area="\0") + def test_repeating_templates(self): + # Templates are excluded by default, as before. + todos = things.todos() + self.assertFalse(any("next_instance_start_date" in todo for todo in todos)) + + templates = things.todos(is_repeating_template=True) + self.assertEqual(1, len(templates)) + template = templates[0] + self.assertEqual("Repeating To-Do", template["title"]) + self.assertEqual("2030-01-01", template["next_instance_start_date"]) + self.assertIsNone(template["start_date"]) + + both = things.todos(is_repeating_template=None) + self.assertEqual(len(todos) + 1, len(both)) + + # The instance Things created from the template is a regular to-do. + instance = things.get("K9bx7h1xCJdevvyWardZDq") + self.assertNotIn("next_instance_start_date", instance) + self.assertIn("next_instance_start_date", things.get(template["uuid"])) + + # The next-instance date filters like a start date. + for value, expected in (("future", 1), ("past", 0), (False, 0)): + templates = things.todos( + is_repeating_template=True, next_instance_start_date=value + ) + self.assertEqual(expected, len(templates)) + + with self.assertRaises(ValueError): + things.tasks(is_repeating_template="invalid_value") + with self.assertRaises(ValueError): + things.tasks(next_instance_start_date="invalid_value") + def test_tasks_stopdate_timezones(self): # see https://github.com/thingsapi/things.py/issues/117 # this test looks at changes to two tasks based on timezone, on either side of midnight UTC diff --git a/things/api.py b/things/api.py index 2a4b766..21568e5 100644 --- a/things/api.py +++ b/things/api.py @@ -127,6 +127,18 @@ def tasks(uuid=None, include_items=False, **kwargs): # noqa: C901 only return tasks whose context has been trashed. - `context_trashed == None`, include both kind of tasks. + is_repeating_template : bool or None, optional, default False + A repeating to-do is stored as a template, from which Things + creates each instance. A template has no start date; instead it + carries `next_instance_start_date`, the date Things will create + the next instance. Only templates have that field. + - `is_repeating_template == False` (default), exclude templates. + - `is_repeating_template == True`, only include templates. + - `is_repeating_template == None`, include both kind of tasks. + + next_instance_start_date : same options as start_date, signifies the date + Things will create the next instance of a repeating to-do (templates only) + last : str, optional Limit returned tasks to tasks created within the last X days, weeks, or years. For example: '3d', '5w', or '1y'. @@ -183,6 +195,8 @@ def tasks(uuid=None, include_items=False, **kwargs): # noqa: C901 12 >>> things.tasks(status='completed', last='1w', count_only=True) 0 + >>> things.tasks(is_repeating_template=True) + [{'uuid': 'N1PJHsbjct4mb1bhcs7aHa', 'type': 'to-do', 'title': 'Repeating To-Do', ... """ database = pop_database(kwargs) @@ -532,12 +546,36 @@ def upcoming(**kwargs): """ Read Upcoming tasks into dicts. + The output aims to be in the same order as Upcoming in Things.app. + Repeating to-dos use `next_instance_start_date` instead of `start_date`. + Note: unscheduled tasks with a deadline are not included here. - See the `things.api.deadline` function instead. + See the `things.api.deadlines` function instead. For details on parameters, see `things.api.tasks`. """ - return tasks(start_date="future", start="Someday", **kwargs) + database = pop_database(kwargs) + kwargs["database"] = database + + scheduled = tasks(start_date="future", start="Someday", **kwargs) + repeating = tasks( + is_repeating_template=True, + next_instance_start_date="future", + start="Someday", + **kwargs, + ) + if kwargs.get("count_only"): + return scheduled + repeating + + result = [*scheduled, *repeating] + result.sort( + key=lambda task: ( + task["start_date"] or task["next_instance_start_date"], + task["today_index"], + task["index"], + ) + ) + return result def anytime(**kwargs): diff --git a/things/database.py b/things/database.py index 35fe479..2355412 100644 --- a/things/database.py +++ b/things/database.py @@ -47,6 +47,13 @@ TRASHED_TO_FILTER = {True: "trashed = 1", False: "trashed = 0"} +# A repeating to-do is stored as a template row carrying a recurrence rule; +# Things creates each instance from it. See `things.api.tasks`. +REPEATING_TEMPLATE_TO_FILTER = { + True: "rt1_recurrenceRule IS NOT NULL", + False: "rt1_recurrenceRule IS NULL", +} + TYPE_TO_FILTER = { "to-do": "type = 0", "project": "type = 1", @@ -69,6 +76,7 @@ "checklist", "heading", "heading_title", + "next_instance_start_date", "project", "project_title", "reminder_time", @@ -104,6 +112,8 @@ # See `convert_isodate_sql_expression_to_thingsdate` for details. DATE_DEADLINE = "deadline" # INTEGER: YYYYYYYYYYYMMMMDDDDD0000000, in binary DATE_START = "startDate" # INTEGER: YYYYYYYYYYYMMMMDDDDD0000000, in binary +# INTEGER: YYYYYYYYYYYMMMMDDDDD0000000, in binary; set on repeating templates only +DATE_NEXT_INSTANCE_START = "rt1_nextInstanceStartDate" # See 'convert_thingstime_sql_expression_to_isotime' for details. REMINDER_TIME = "reminderTime" # INTEGER: hhhhhmmmmmm00000000000000000000, in binary @@ -126,9 +136,6 @@ IS_ANYTIME = START_TO_FILTER["Anytime"] IS_SOMEDAY = START_TO_FILTER["Someday"] -# Repeats -IS_NOT_RECURRING = "rt1_recurrenceRule IS NULL" - # Trash IS_TRASHED = TRASHED_TO_FILTER[True] @@ -141,8 +148,6 @@ # IS_NOT_SCHEDULED = f"{DATE_START} IS NULL" # IS_DEADLINE = f"{DATE_DEADLINE} IS NOT NULL" # RECURRING_IS_NOT_PAUSED = "rt1_instanceCreationPaused = 0" -# IS_RECURRING = "rt1_recurrenceRule IS NOT NULL" -# RECURRING_HAS_NEXT_STARTDATE = ("rt1_nextInstanceStartDate IS NOT NULL") # IS_NOT_TRASHED = TRASHED_TO_FILTER[False] # pylint: disable=R0904,R0902 @@ -214,6 +219,8 @@ def get_tasks( # pylint: disable=R0914,R0913,R0917 deadline_suppressed: bool | None = None, trashed: bool | None = False, context_trashed: bool | None = False, + is_repeating_template: bool | None = False, + next_instance_start_date: str | bool | None = None, last: str | None = None, search_query: str | None = None, index: str = "index", @@ -231,11 +238,17 @@ def get_tasks( # pylint: disable=R0914,R0913,R0917 validate("deadline_suppressed", deadline_suppressed, [None, True, False]) validate("start", start, [None] + list(START_TO_FILTER)) validate_date("start_date", start_date) + validate_date("next_instance_start_date", next_instance_start_date) validate_date("stop_date", stop_date) validate("status", status, [None] + list(STATUS_TO_FILTER)) validate("trashed", trashed, [None] + list(TRASHED_TO_FILTER)) validate("type", type, [None] + list(TYPE_TO_FILTER)) validate("context_trashed", context_trashed, [None, True, False]) + validate( + "is_repeating_template", + is_repeating_template, + [None] + list(REPEATING_TEMPLATE_TO_FILTER), + ) validate("index", index, list(INDICES)) validate_offset("last", last) @@ -251,6 +264,13 @@ def get_tasks( # pylint: disable=R0914,R0913,R0917 status_filter: str = STATUS_TO_FILTER.get(status, "") # type: ignore trashed_filter: str = TRASHED_TO_FILTER.get(trashed, "") # type: ignore type_filter: str = TYPE_TO_FILTER.get(type, "") # type: ignore + repeating_template_filter: str = REPEATING_TEMPLATE_TO_FILTER.get( + is_repeating_template, # type: ignore + "", + ) + next_instance_start_date_filter = make_thingsdate_filter( + f"TASK.{DATE_NEXT_INSTANCE_START}", next_instance_start_date + ) # Sometimes a task is _not_ set to trashed, but its context # (project or heading it is contained within) is set to trashed. @@ -270,7 +290,8 @@ def get_tasks( # pylint: disable=R0914,R0913,R0917 ) where_predicate = f""" - TASK.{IS_NOT_RECURRING} + TRUE + {repeating_template_filter and f"AND TASK.{repeating_template_filter}"} {trashed_filter and f"AND TASK.{trashed_filter}"} {project_trashed_filter} {project_of_heading_trashed_filter} @@ -284,6 +305,7 @@ def get_tasks( # pylint: disable=R0914,R0913,R0917 {make_filter("TASK.deadlineSuppressionDate", deadline_suppressed)} {make_filter("TAG.title", tag)} {make_thingsdate_filter(f"TASK.{DATE_START}", start_date)} + {next_instance_start_date_filter} {make_unixtime_filter(f"TASK.{DATE_STOP}", stop_date)} {make_thingsdate_filter(f"TASK.{DATE_DEADLINE}", deadline)} {make_unixtime_range_filter(f"TASK.{DATE_CREATED}", last)} @@ -519,6 +541,9 @@ def make_tasks_sql_query(where_predicate=None, order_predicate=None): reminder_time_expression = convert_thingstime_sql_expression_to_isotime( f"TASK.{REMINDER_TIME}" ) + next_instance_start_date_expression = convert_thingsdate_sql_expression_to_isodate( + null_if_unset_thingsdate(f"TASK.{DATE_NEXT_INSTANCE_START}") + ) return f""" SELECT DISTINCT @@ -568,6 +593,7 @@ def make_tasks_sql_query(where_predicate=None, order_predicate=None): WHEN CHECKLIST_ITEM.uuid IS NOT NULL THEN 1 END AS checklist, {start_date_expression} AS start_date, + {next_instance_start_date_expression} AS next_instance_start_date, {deadline_expression} AS deadline, {reminder_time_expression} AS "reminder_time", datetime(TASK.{DATE_STOP}, "unixepoch", "localtime") AS "stop_date", @@ -1118,6 +1144,36 @@ def match_date(value): return re.fullmatch(r"(=|==|<|<=|>|>=)?(\d{4}-\d{2}-\d{2})", value) +def null_if_unset_thingsdate(sql_expression: str) -> str: + """ + Return SQL expression as string. + + It is NULL when the "Things date" is unset, else the Things date itself. + Things stores 0001-01-01 instead of NULL in some date columns, such as + `rt1_nextInstanceStartDate` when a repeating to-do has no next instance. + Sometimes bits below the day field are set as well (69769 rather than + 69760), so any date in year 1 counts as unset. + + Parameters + ---------- + sql_expression : str + A sql expression pointing to a "Things date" integer in + format YYYYYYYYYYYMMMMDDDDD0000000, in binary. + See: `convert_isodate_sql_expression_to_thingsdate` for details. + + Example + ------- + >>> null_if_unset_thingsdate('rt1_nextInstanceStartDate') + 'CASE WHEN rt1_nextInstanceStartDate >= 135296 \ + THEN rt1_nextInstanceStartDate END' + """ + first_real_thingsdate = isodate_to_yyyyyyyyyyymmmmddddd("0002-01-01") + return ( + f"CASE WHEN {sql_expression} >= {first_real_thingsdate}" + f" THEN {sql_expression} END" + ) + + def prettify_sql(sql_query): """Make a SQL query easier to read for humans.""" # remove indentation and leading and trailing whitespace