Metadata-Version: 2.1
Name: things.py
Version: 0.0.14
Summary: A simple Python 3 library to read your Things app data.
Home-page: https://github.com/thingsapi/things.py
Author: Alexander Willner, Michael B.
Author-email: alex@willner.ws
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Natural Language :: English
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# Things Python API

_things.py_ is a simple Python 3 library to read data from your [Things app](https://culturedcode.com/things).

[![GitHub Release](https://img.shields.io/github/v/release/thingsapi/things.py?sort=semver)](https://github.com/thingsapi/things.py/releases)
[![Build Status](https://github.com/thingsapi/things.py/workflows/Build-Test/badge.svg)](https://github.com/thingsapi/things.py/actions)
[![Coverage Status](https://codecov.io/gh/thingsapi/things.py/branch/main/graph/badge.svg?token=DBWGKAEYAP)](https://codecov.io/gh/thingsapi/things.py)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=thingsapi_things.py&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=thingsapi_things.py)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/thingsapi/things.py/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/thingsapi/things.py/?branch=main)
[![GitHub Issues](https://img.shields.io/github/issues/thingsapi/things.py)](https://github.com/thingsapi/things.py/issues)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/things.py?label=pypi%20downloads)](https://pypi.org/project/things.py/)
[![GitHub Download Count](https://img.shields.io/github/downloads/thingsapi/things.py/total.svg)](https://github.com/thingsapi/things.py/releases)

## Table of Contents

- [Install](#install)
- [Examples](#examples)
- [Documentation](#documentation)
- [Background](#background)
- [Things URLs](#things-urls)
- [Used By](#used-by)

## Install

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

## Examples

```python
>>> 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](https://culturedcode.com/things/support/articles/2982272/#get-the-things-3-database-file)). This format is intended to be machine-readable, not human-readable. The aim of this project is let you access all your 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](https://github.com/thingsapi/things.py/issues).

### 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 can be found here: https://thingsapi.github.io/things.py/things/api.html

## Things URLs

You can make good use of the `uuid` to link to to-dos, areas, tags, and more from other apps. Read more [here](https://culturedcode.com/things/blog/2018/02/hey-things/).

## Used By

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

- [KanbanView](https://github.com/AlexanderWillner/KanbanView)
- [Things CLI](https://github.com/thingsapi/things-cli)
- [ThingsStats](https://github.com/lmgibson/ThingsStats)


