Skip to main content

Things Python API

things.py is a simple Python 3 library to read data from your Things app.

GitHub Release Build Status Coverage Status Maintainability Rating GitHub Issues License PyPI - Downloads GitHub Download Count

Table of Contents

Install

$ pip3 install things.py
# or
$ git clone https://github.com/thingsapi/things.py && cd things.py && make install

Examples

>>> import things
>>> things.todos()
[{'uuid': '2Ukg8I2nLukhyEM7wYiBeb',
  'type': 'to-do',
  'title': 'Make reservation for dinner',
  'project': 'bNj6TPdKYhY6fScvXWVRDX',
  ...},
 {'uuid': 'RLZroza3jz0XPs3uAlynS7',
  'type': 'to-do',
  'title': 'Buy a whiteboard and accessories',
  'project': 'w8oSP1HjWstPin8RMaJOtB',
  'notes': "Something around 4' x 3' that's free-standing, two-sided, and magnetic.",
  'checklist': True,
  ...

>>> things.todos('RLZroza3jz0XPs3uAlynS7')
{'uuid': 'RLZroza3jz0XPs3uAlynS7',
 'type': 'to-do',
 'title': 'Buy a whiteboard and accessories',
 ...
 'checklist': [
     {'title': 'Cleaning Spray', 'status': 'completed', ...},
     {'title': 'Magnetic Eraser', 'status': 'incomplete', ...},
     {'title': 'Round magnets', 'status': 'incomplete', ...}
 ]
 ...
}

>>> things.projects()
[{'uuid': 'bNj6TPdKYhY6fScvXWVRDX',
  'type': 'project',
  'title': 'Throw Birthday Party',
  'area': 'bNj6TPdKYhY6fScvXWVRDX',
  ...},
 {'uuid': 'w8oSP1HjWstPin8RMaJOtB',
  'type': 'project',
  'title': 'Set Up Home Office',
  'area': 'Gw9QefIdgR6nPEoY5hBNSh',
  ...

>>> things.areas()
[{'uuid': 'ToLxnnBrWkfHC3tkx4vxdV',
  'type': 'area',
  'title': 'Family',
  ...},
 {'uuid': 'Gw9QefIdgR6nPEoY5hBNSh',
  'type': 'area',
  'title': 'Apartment',
  ...

>>> things.tags()
[{'uuid': 'CKILg3kKF2jlCRisNFcqOj',
  'type': 'tag',
  'title': 'Home',
  'shortcut': None},
 {'uuid': 'gfmpz8zxnyfqMDvRi3E8vo',
  'type': 'tag',
  'title': 'Office',
  'shortcut': None},
 ...

>>> things.get('CKILg3kKF2jlCRisNFcqOj')
{'uuid': 'CKILg3kKF2jlCRisNFcqOj',
  'type': 'tag',
  'title': 'Home',
  'shortcut': None}

Background

The task management app Things stores all your to-dos in a SQLite database file (details here). This format is intended to be machine-readable, not human-readable. The aim of this project is to let you access all your Things data in a human-readable way. We thereby stay as true to the database as possible while doing SQL joins and transformations to aid understanding of the data. Note that you can print the SQL used by adding the parameter print_sql=True to most API calls.

If any aspect of the API seems overly complex or doesn't meet your needs, please don't hesitate to add a new issue here.

Terminology

Here are the core technical terms used involving the database:

  • area
  • tag
  • task
    • type
      • 'to-do': can have checklists;
      • 'project': can have to-dos and headings;
      • 'heading': part of a project; groups to-dos.
    • status: 'incomplete', 'canceled', or 'completed'
    • trashed: True or False
    • start: 'Inbox', 'Anytime', or 'Someday'
  • checklist item (contained within a to-do)

Documentation

The full documentation for this library can be found here: https://thingsapi.github.io/things.py/things/api.html

Things URL Scheme

You can make good use of the uuid to link to to-dos, areas, tags, and more from other apps. Doing updates are possible as well. Read an introduction here and see the documentation here.

Contributing

We welcome contributions to things.py! Before submitting a pull request, please take a moment to look over the contributing guidelines first.

Used By

The following open-source projects make use of this library:

Metadata

Release files for things.py 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for things.py 1.1.0
File Size Uploaded Provenance Actions
things_py-1.1.0.tar.gz 32.1 kB Without provenance Details for things_py-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for things.py 1.1.0
File Interpreter ABI Platform Actions
things_py-1.1.0-py3-none-any.whl Python 3 none any Details for things_py-1.1.0-py3-none-any.whl

Total release size: 62.7 kB

Release files / things_py-1.1.0.tar.gz

Download URL things_py-1.1.0.tar.gz
Size 32.1 kB
Tags Source
SHA-256 checksum
How to use checksums
74da445f499dc647e01671a3aeebffb2e1b2c032cef98b6704dc21c6acb36d6f
BLAKE2b-256 checksum
How to use checksums
b261be69a754376444f85bfd7ba41d820353fc1ed2759aef4ba3c3177f4757dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / things_py-1.1.0-py3-none-any.whl

Download URL things_py-1.1.0-py3-none-any.whl
Size 30.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ddc46de352067ff0c783c2fc0fc6d9f636a0e58b0ee3e486f65d1883ffad88df
BLAKE2b-256 checksum
How to use checksums
f751e3738a2f8220a2f922dd1b5ea715cdd38edc1ff5784b7c46ba927e619419
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Security for things.py 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page