things.api

  1"""
  2Module implementing the Things API.
  3
  4The terms of the API aim to match those used in the Things app and
  5Things URL Scheme. In some specific cases we instead choose to use terms
  6that occur in the Things SQL database to closer reflect its underlying
  7data structures. Whenever that happens, we define the new term here.
  8"""
  9
 10import os
 11from shlex import quote
 12from typing import Dict, List, Union
 13import urllib.parse
 14
 15from things.database import Database
 16
 17
 18# --------------------------------------------------
 19# Core functions
 20# --------------------------------------------------
 21
 22
 23def tasks(uuid=None, include_items=False, **kwargs):  # noqa: C901
 24    """
 25    Read tasks into dicts.
 26
 27    Note: "task" is a technical term used in the database to refer to a
 28    to-do, project, or heading. For details, check the "type"-parameter.
 29
 30    Per default, only tasks marked as incomplete are included. If you
 31    want to include completed or canceled tasks in the result, check the
 32    "status"-parameter.
 33
 34    Parameters
 35    ----------
 36    uuid : str or None, optional
 37        Any valid task uuid. If None, then return all tasks matched.
 38
 39    include_items : bool, default False
 40        Include items contained within a task. These might include
 41        checklist items, headings, and to-dos.
 42
 43    type : {'to-do', 'heading', 'project', None}, optional
 44        Only return a specific type of task:
 45        - `'to-do'`:    may have a checklist; may be in an area and have tags.
 46        - `'project'`:  may have to-dos and headings; may be in an area and
 47                        have tags.
 48        - `'heading'`:  part of a project; groups tasks.
 49        - `None` (default): return all types of tasks.
 50
 51    status : {'incomplete', 'completed', 'canceled', None}, optional, \
 52        default 'incomplete'
 53
 54        Only include tasks matching that status. If `status == None`,
 55        then include tasks with any status value.
 56
 57    start : {'Inbox', 'Anytime', 'Someday', None}, optional
 58        Only include tasks matching that start value. If the argument is
 59        `None` (default), then include tasks with any start value.
 60
 61    area : str or bool or None, optional
 62        Any valid uuid of an area. Only include tasks matching that area.
 63        Special cases:
 64        - `area == False`, only include tasks _without_ an area.
 65        - `area == True`, only include tasks _with_ an area.
 66        - `area == None` (default), then include all tasks.
 67
 68    project : str or bool or None, optional
 69        Any valid uuid of a project. Only include tasks matching that project.
 70        Special cases:
 71        - `project == False`, only include tasks _without_ a project.
 72        - `project == True`, only include tasks _with_ a project.
 73        - `project == None` (default), then include all tasks.
 74
 75    heading : str or None, optional
 76        Any valid uuid of a heading. Only include tasks matching that heading.
 77        Special cases:
 78        - `heading == False`, only include tasks _without_ a heading.
 79        - `heading == True`, only include tasks _with_ a heading.
 80        - `heading == None` (default), then include all tasks.
 81
 82    tag : str or bool or None, optional
 83        Any valid title of a tag. Only include tasks matching that tag.
 84        Special cases:
 85        - `tag == False`, only include tasks _without_ tags.
 86        - `tag == True`, only include tasks _with_ tags.
 87        - `tag == None` (default), then include all tasks.
 88
 89    start_date : bool, str or None, optional
 90        - `start_date == False`, only include tasks _without_ a start date.
 91        - `start_date == True`, only include tasks with a start date.
 92        - `start_date == 'future'`, only include tasks with a future start date.
 93        - `start_date == 'past'`, only include tasks with a past start date.
 94          Note: this includes today's date.
 95        - `start_date == '[operator]YYYY-MM-DD'`; match with optional operator,
 96          for example: '2023-05-22', '<=2023-05-22', or '>2023-05-22'.
 97        - `start_date == None` (default), then include all tasks.
 98
 99    stop_date : same options as start_date, signifies the date of completion
100
101    deadline : same options as start_date, signifies the deadline
102
103    deadline_suppressed : bool or None, optional
104        "deadline suppressed" is a technical term used in the database.
105        When tasks have an overdue deadline they show up in Today.
106        Some of us "suppress" some tasks, that is, move them out of
107        Today and into Inbox, Anytime, or Someday. For those moved tasks
108        the deadline is said to be suppressed.
109        - `deadline_suppressed == True`, only include tasks with deadlines
110          and whose deadlines have been suppressed.
111        - `deadline_suppressed == False`, include any task _except_ those
112          with suppressed deadlines.
113        - `deadline_suppressed == None` (default), include any task.
114
115    trashed : bool or None, optional, default False
116        - `trashed == False` (default), only include non-trashed tasks.
117        - `trashed == True`, only include trashed tasks.
118        - `trashed == None`, include both kind of tasks.
119
120    context_trashed : bool or None, optional, default False
121        Some tasks may be within a context of a project or a heading.
122        This manages how to handle such tasks. The other tasks are not
123        affected by this setting.
124
125        - `context_trashed == False` (default), for tasks within a context,
126           only return tasks whose context has _not_ been trashed.
127        - `context_trashed == True`, for tasks within a context,
128           only return tasks whose context has been trashed.
129        - `context_trashed == None`, include both kind of tasks.
130
131    last : str, optional
132        Limit returned tasks to tasks created within the last X days,
133        weeks, or years. For example: '3d', '5w', or '1y'.
134
135        Takes as input an offset string of the format 'X[d/w/y]' where X
136        is a non-negative  integer that is followed by 'd', 'w', or 'y'
137        which stand for 'days', 'weeks', and 'years', respectively.
138
139    search_query : str, optional
140        The string value is passed to the SQL LIKE operator. It can thus
141        include placeholders such as '%' and '_'. Per default, it is
142        wrapped in '% ... %'.
143
144        Currently titles and notes of to-dos, projects, headings, and areas
145        are taken into account.
146
147    index : {'index', 'todayIndex'}, default 'index'
148        Database field to order result by.
149
150    count_only : bool, default False
151        Only output length of result. This is done by a SQL COUNT query.
152
153    print_sql : bool, default False
154        Print every SQL query performed. Some may contain '?' and ':'
155        characters, which correspond to SQLite parameter tokens.
156        See https://www.sqlite.org/lang_expr.html#varparam
157
158    filepath : str, optional
159        Any valid path of a SQLite database file generated by the Things app.
160        If the environment variable `THINGSDB` is set, then use that path.
161        Otherwise, access the default database path.
162
163    database : things.database.Database, optional
164        Any valid database object previously instantiated.
165
166    Returns
167    -------
168    list of dict (default)
169        Representing multiple tasks.
170    dict (if `uuid` is given)
171        Representing a single task.
172    int (`count_only == True`)
173        Count of matching Tasks.
174
175    Examples
176    --------
177    >>> things.tasks()
178    [{'uuid': '6Hf2qWBjWhq7B1xszwdo34', 'type': 'to-do', 'title':...
179    >>> things.tasks('DfYoiXcNLQssk9DkSoJV3Y')
180    {'uuid': 'DfYoiXcNLQssk9DkSoJV3Y', 'type': 'to-do', 'title': ...
181    >>> things.tasks(area='hIo1FJlAYGKt1Yj38vzKc3', include_items=True)
182    []
183    >>> things.tasks(status='completed', count_only=True)
184    12
185    >>> things.tasks(status='completed', last='1w', count_only=True)
186    0
187
188    """
189    database = pop_database(kwargs)
190    result = database.get_tasks(
191        uuid=uuid, status=kwargs.pop("status", "incomplete"), **kwargs
192    )
193
194    if kwargs.get("count_only"):
195        return result
196
197    # overwrite `include_items` if fetching a single task.
198    if uuid:
199        include_items = True
200
201    for task in result:
202        # TK: How costly of an operation is it to do this for every task?
203        # IF costly, then can it be made significantly more efficient
204        # by optimizing SQL calls?
205
206        if task.get("tags"):
207            task["tags"] = database.get_tags(task=task["uuid"])
208
209        if not include_items:
210            continue
211
212        # include items
213        if task["type"] == "to-do":
214            if task.get("checklist"):
215                task["checklist"] = database.get_checklist_items(task["uuid"])
216        elif task["type"] == "project":
217            project = task
218            project["items"] = items = tasks(
219                project=project["uuid"],
220                context_trashed=None,
221                include_items=True,
222                database=database,
223            )
224            # to-dos without headings appear before headings in app
225            items.sort(key=lambda item: item["type"], reverse=True)
226        elif task["type"] == "heading":
227            heading = task
228            heading["items"] = tasks(
229                type="to-do",
230                heading=heading["uuid"],
231                context_trashed=None,
232                include_items=True,
233                database=database,
234            )
235
236    if uuid:
237        result = result[0]
238
239    return result
240
241
242def areas(uuid=None, include_items=False, **kwargs):
243    """
244    Read areas into dicts.
245
246    Parameters
247    ----------
248    uuid : str or None, optional
249        Any valid uuid of an area. If None, then return all areas.
250
251    include_items : bool, default False
252        Include tasks and projects in each area.
253
254    tag : str or bool or None, optional
255        Any valid title of a tag. Only include areas matching that tag.
256        Special cases:
257        - `tag == False`, only include areas _without_ tags.
258        - `tag == True`, only include areas _with_ tags.
259        - `tag == None`, then ignore any tags present, that is,
260           include areas both with and without tags.
261
262    count_only : bool, default False
263        Only output length of result. This is done by a SQL COUNT query.
264
265    filepath : str, optional
266        Any valid path of a SQLite database file generated by the Things app.
267        If no path is provided, then access the default database path.
268
269    database : things.database.Database, optional
270        Any valid `things.database.Database` object previously instantiated.
271
272    Returns
273    -------
274    list of dict (default)
275        Representing Things areas.
276    dict (if `uuid` is given)
277        Representing a single Things area.
278    int (`count_only == True`)
279        Count of matching areas.
280
281    Examples
282    --------
283    >>> things.areas()
284    [{'uuid': 'Y3JC4XeyGWxzDocQL4aobo', 'type': 'area', 'title': 'Area 3'}, ...
285    >>> things.areas(tag='Home')
286    []
287    >>> things.areas(uuid='DciSFacytdrNG1nRaMJPgY')
288    {'uuid': 'DciSFacytdrNG1nRaMJPgY', 'type': 'area', 'title': 'Area 1', ...
289    >>> things.areas(include_items=True, tag='Errand')
290    [{'uuid': 'DciSFacytdrNG1nRaMJPgY', 'type': 'area', 'title': 'Area 1', ...
291    """
292    database = pop_database(kwargs)
293    result = database.get_areas(uuid=uuid, **kwargs)
294
295    if kwargs.get("count_only"):
296        return result
297
298    for area in result:
299        if area.get("tags"):
300            area["tags"] = database.get_tags(area=area["uuid"])
301        if include_items:
302            area["items"] = tasks(
303                area=area["uuid"], include_items=True, database=database
304            )
305
306    if uuid:
307        result = result[0]
308
309    return result
310
311
312def tags(title=None, include_items=False, **kwargs):
313    """
314    Read tags into dicts.
315
316    Parameters
317    ----------
318    title : str, optional
319        Any valid title of a tag. Include all items of said tag.
320        If None, then return all tags.
321
322    include_items : bool, default False
323        For each tag, include items tagged with that tag.
324        Items may include areas, tasks, and projects.
325
326    area : str, optional
327        Valid uuid of an area. Return tags of said area.
328
329    task : str, optional
330        Valid uuid of a task. Return tags of said task.
331
332    titles_only : bool, default False
333        If True, only return list of titles of tags.
334
335    filepath : str, optional
336        Any valid path of a SQLite database file generated by the Things app.
337        If no path is provided, then access the default database path.
338
339    database : things.database.Database, optional
340        Any valid database object previously instantiated.
341
342    Returns
343    -------
344    list of dict (default)
345        Representing tags.
346    list of str (if `titles_only == True` or area / task is given)
347        Representing tag titles.
348    dict (if `title` is given)
349        Representing a single Things tag.
350
351    Examples
352    --------
353    >>> things.tags()
354    [{'uuid': 'H96sVJwE7VJveAnv7itmux', 'type': 'tag', 'title': 'Errand', ...
355    >>> things.tags('Home')
356    {'uuid': 'CK9dARrf2ezbFvrVUUxkHE', 'type': 'tag', 'title': 'Home', ...
357    >>> things.tags(include_items=True)
358    [{'uuid': 'H96sVJwE7VJveAnv7itmux', 'type': 'tag', 'title': 'Errand', ...
359    >>> things.tags(task='2Ukg8I2nLukhyEM7wYiBeb')
360    []
361    """
362    database = pop_database(kwargs)
363    result = database.get_tags(title=title, **kwargs)
364
365    if include_items:
366        for tag in result:
367            tag_title = tag["title"]
368            tag["items"] = [
369                *areas(tag=tag_title, database=database),
370                *tasks(tag=tag_title, database=database),
371            ]
372
373    if title:
374        result = result[0]
375
376    return result
377
378
379def checklist_items(todo_uuid, **kwargs):
380    """
381    Read checklist items of to-dos into dicts.
382
383    Note: checklists are contained in the return value of
384    `things.todos(todo_uuid)` and `things.tasks(todo_uuid)`.
385
386    Parameters
387    ----------
388    todo_uuid : str, optional
389        A valid to-do uuid.
390
391    Returns
392    -------
393    list of dict
394        Checklist items.
395    """
396    database = pop_database(kwargs)
397    return database.get_checklist_items(todo_uuid=todo_uuid)
398
399
400# --------------------------------------------------
401# Utility API functions derived from above
402# --------------------------------------------------
403
404
405def search(query: str, **kwargs) -> List[Dict]:
406    """
407    Search tasks in the database.
408
409    Currently any part of a title and note of a to-do, project,
410    heading, or area is matched.
411
412    See the `search_query` parameter of `things.api.tasks` for details.
413
414    Examples
415    --------
416    >>> things.search('Today%yellow')
417    [{'uuid': '6Hf2qWBjWhq7B1xszwdo34',
418      'type': 'to-do',
419      'title': 'Upcoming To-Do in Today (yellow)',
420      'status': 'incomplete',
421      'notes': '',
422      ...
423    """
424    return tasks(search_query=query, **kwargs)
425
426
427def get(uuid, default=None, **kwargs):
428    """
429    Find an object by uuid. If not found, return `default`.
430
431    Currently supports tasks, projects, headings, areas, and tags.
432    """
433    try:
434        return tasks(uuid=uuid, **kwargs)
435    except ValueError:
436        pass
437
438    try:
439        return areas(uuid=uuid, **kwargs)
440    except ValueError:
441        pass
442
443    for tag in tags(**kwargs):
444        if tag["uuid"] == uuid:
445            return tag
446
447    return default
448
449
450# Filter by object type
451
452
453def todos(uuid=None, **kwargs):
454    """
455    Read to-dos into dicts.
456
457    See `things.api.tasks` for details on the optional parameters.
458    """
459    return tasks(uuid=uuid, type="to-do", **kwargs)
460
461
462def projects(uuid=None, **kwargs):
463    """
464    Read projects into dicts.
465
466    See `things.api.tasks` for details on the optional parameters.
467    """
468    return tasks(uuid=uuid, type="project", **kwargs)
469
470
471# Filter by collections in the Things app sidebar.
472
473
474def inbox(**kwargs):
475    """
476    Read Inbox into dicts.
477
478    See `things.api.tasks` for details on the optional parameters.
479    """
480    return tasks(start="Inbox", **kwargs)
481
482
483def today(**kwargs):
484    """
485    Read Today's tasks into dicts.
486
487    Note: The Things database reflects the state of the Things app when
488    it was last opened. For the Today tasks that means the database
489    might not be up to date anymore if you didn't open the app recently.
490    To get around this limitation, we here make a prediction of what
491    tasks would show up in Today if you were to open the app right now.
492    This prediction does not include repeating tasks at this time.
493
494    See `things.api.tasks` for details on the optional parameters.
495    """
496    database = pop_database(kwargs)
497    kwargs["database"] = database
498
499    regular_today_tasks = tasks(
500        start_date=True,
501        start="Anytime",
502        index="todayIndex",
503        **kwargs,
504    )
505
506    # Predictions of new to-dos indicated by a yellow dot in the app.
507
508    unconfirmed_scheduled_tasks = tasks(
509        start_date="past",
510        start="Someday",
511        index="todayIndex",
512        **kwargs,
513    )
514
515    unconfirmed_overdue_tasks = tasks(
516        start_date=False,
517        deadline="past",
518        deadline_suppressed=False,
519        **kwargs,
520    )
521
522    result = [
523        *regular_today_tasks,
524        *unconfirmed_scheduled_tasks,
525        *unconfirmed_overdue_tasks,
526    ]
527    result.sort(key=lambda task: (task["today_index"], task["start_date"]))
528
529    return result
530
531
532def upcoming(**kwargs):
533    """
534    Read Upcoming tasks into dicts.
535
536    Note: unscheduled tasks with a deadline are not included here.
537    See the `things.api.deadline` function instead.
538
539    For details on parameters, see `things.api.tasks`.
540    """
541    return tasks(start_date="future", start="Someday", **kwargs)
542
543
544def anytime(**kwargs):
545    """
546    Read Anytime tasks into dicts.
547
548    See `things.api.tasks` for details on the optional parameters.
549    """
550    return tasks(start="Anytime", **kwargs)
551
552
553def someday(**kwargs):
554    """
555    Read Someday tasks into dicts.
556
557    See `things.api.tasks` for details on the optional parameters.
558    """
559    return tasks(start_date=False, start="Someday", **kwargs)
560
561
562def logbook(**kwargs):
563    """
564    Read Logbook tasks into dicts.
565
566    See `things.api.tasks` for details on the optional parameters.
567    """
568    result = [*canceled(**kwargs), *completed(**kwargs)]
569    result.sort(key=lambda task: task["stop_date"], reverse=True)
570    return result
571
572
573def trash(**kwargs):
574    """
575    Read Trash tasks into dicts.
576
577    See `things.api.tasks` for details on the optional parameters.
578    """
579    return tasks(
580        trashed=True,
581        context_trashed=kwargs.pop("context_trashed", None),
582        status=kwargs.pop("status", None),
583        **kwargs,
584    )
585
586
587# Filter by various task properties
588
589
590def canceled(**kwargs):
591    """
592    Read canceled tasks into dicts.
593
594    See `things.api.tasks` for details on the optional parameters.
595    """
596    return tasks(status="canceled", **kwargs)
597
598
599def completed(**kwargs):
600    """
601    Read completed tasks into dicts.
602
603    See `things.api.tasks` for details on the optional parameters.
604
605    Examples
606    --------
607    >>> things.completed(count_only=True)
608    12
609    >>> things.completed(type='project', count_only=True)
610    0
611    >>> things.completed(type='to-do', last='1w')
612    []
613    """
614    return tasks(status="completed", **kwargs)
615
616
617def deadlines(**kwargs):
618    """
619    Read tasks with deadlines into dicts.
620
621    See `things.api.tasks` for details on the optional parameters.
622    """
623    result = tasks(deadline=True, **kwargs)
624    result.sort(key=lambda task: task["deadline"])
625    return result
626
627
628def last(offset, **kwargs):
629    """
630    Read tasks created within last X days, weeks, or years into dicts.
631
632    Per default, only incomplete tasks are included, but do see
633    `things.api.tasks` for details on the optional parameters.
634
635    Parameters
636    ----------
637    offset : str
638        A valid date offset such as '3d', '5w', or '1y'.
639        For details, see the `last` parameter of `things.api.tasks`.
640
641    Returns
642    -------
643    list of dict
644        Tasks within offset ordered by creation date. Newest first.
645
646    Examples
647    --------
648    >>> things.last('3d')
649    []
650    >>> things.last('1w', status='completed')
651    []
652    >>> things.last('1y', tag='Important', status='completed', count_only=True)
653    0
654
655    """
656    if offset is None:
657        raise ValueError(f"Invalid offset type: {offset!r}")
658
659    result = tasks(last=offset, **kwargs)
660    if result:
661        result.sort(key=lambda task: task["created"], reverse=True)
662
663    return result
664
665
666# Interact with Things app
667
668
669def token(**kwargs) -> Union[str, None]:
670    """
671    Read the Things URL scheme authentication token.
672
673    You can make good use of this token to modify existing Things data
674    using the Things URL Scheme. For details, see
675    [here](https://culturedcode.com/things/help/url-scheme/).
676    """
677    database = pop_database(kwargs)
678    return database.get_url_scheme_auth_token()
679
680
681def url(uuid=None, command="show", **query_parameters) -> str:
682    """
683    Return a things:///<command>?<query> url.
684
685    For details about available commands and their parameters
686    consult the Things URL Scheme documentation
687    [here](https://culturedcode.com/things/help/url-scheme/).
688
689    Parameters
690    ----------
691    uuid : str or None, optional
692        A valid uuid of any Things object.
693        If `None`, then 'id' is not added as a parameter unless
694        specified in `query_parameters`.
695
696    command : str, default 'show'
697        A valid command name.
698
699    **query_parameters:
700        Additional URL query parameters.
701
702    Examples
703    --------
704    >>> things.url('6Hf2qWBjWhq7B1xszwdo34')
705    'things:///show?id=6Hf2qWBjWhq7B1xszwdo34'
706    >>> things.url(command='update', uuid='6Hf2qWBjWhq7B1xszwdo34', title='new title')
707    'things:///update?id=6Hf2qWBjWhq7B1xszwdo34&title=new%20title&auth-token=vKkylosuSuGwxrz7qcklOw'
708    >>> things.url(command='add', title='new task', when='in 3 days', deadline='in 6 days')
709    'things:///add?title=new%20task&when=in%203%20days&deadline=in%206%20days'
710    >>> query_params = {'title': 'test title', 'list-id': 'ba5d1237-1dfa-4ab8-826b-7c27b517f29d'}
711    >>> things.url(command="add", **query_params)
712    'things:///add?title=test%20title&list-id=ba5d1237-1dfa-4ab8-826b-7c27b517f29d'
713    """
714    if uuid is not None:
715        query_parameters = {"id": uuid, **query_parameters}
716
717    # authenticate if needed
718    if command in ("update", "update-project"):
719        auth_token = query_parameters["auth-token"] = token()
720        if not auth_token:
721            raise ValueError("Things URL scheme authentication token could not be read")
722
723    query_string = urllib.parse.urlencode(
724        query_parameters, quote_via=urllib.parse.quote
725    )
726
727    return f"things:///{command}?{query_string}"
728
729
730# Alias for backwards compatiblity
731link = url
732
733
734def show(uuid):  # noqa
735    """
736    Show a certain uuid in the Things app.
737
738    Parameters
739    ----------
740    uuid : str
741        A valid uuid of any Things object.
742
743    Examples
744    --------
745    >>> tag = things.tags('Home')
746    >>> things.show(tag['uuid'])  # doctest: +SKIP
747    """
748    uri = url(uuid=uuid)
749    os.system(f"open {quote(uri)}")
750
751
752def complete(uuid):  # noqa
753    """
754    Set the status of a certain uuid to complete.
755
756    Parameters
757    ----------
758    uuid : str
759        A valid uuid of a project or to-do.
760
761    Examples
762    --------
763    >>> task = things.todos()[0]       # doctest: +SKIP
764    >>> things.complete(task['uuid'])  # doctest: +SKIP
765    """
766    uri = url(uuid=uuid, command="update", completed=True)
767    os.system(f"open {quote(uri)}")
768
769
770# Helper functions
771
772
773def pop_database(kwargs):
774    """Instantiate non-default database from `kwargs` if provided."""
775    filepath = kwargs.pop("filepath", None)
776    database = kwargs.pop("database", None)
777    print_sql = kwargs.pop("print_sql", False)
778
779    if not database:
780        database = Database(filepath=filepath, print_sql=print_sql)
781    return database