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