alexanderwillner/kanbanview

CLI, API, Web Service and Kanban for Things 3

CLI, API, Web Service and Kanban for Things 3

This repository contains a simple read-only CLI, API and Web Service for Things3. It further includes an example web application to create a visual task-level overview (Kanban) of what is on your plate.

Installation

To safe time and to support the development, consider to buy the pre-compiled binary from the AppStore:

Besides this, you've different options:

1. Download a release.
2. Install the library and command line tools: pip3 install things3-api
3. Star, fork and contribute to the lastest code: git clone https://github.com/AlexanderWillner/KanbanView.git

Configuration

While everything should work out of the box, you might want to change some configuration aspects. To have a GUI for this is Feature Request #19. For the time being, the following default values are shown here and you can change them by creating the file ~/.kanbanviewrc (self compiled version) / ~/Library/Containers/ws.willner.kanbanview/Data/~/.kanbanviewrc (AppStore version) or setting them as environment variables. Note that plain integer tags (such as 5, 15, or 60) are being used to calculate the estimated time of task durations for today:

[DATABASE]
THINGSDB=/Users/myname/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/Things Database.thingsdatabase/main.sqlite
TAG_WAITING=Waiting
TAG_MIT=MIT
TAG_CLEANUP=Cleanup

Application

The Kanban Application allows you to visualize the Things3 database following the Kanban approach (focused on tasks or on projects). It also includes some visualizations. There are different implementations of the application available.

The static version creates a snapshot of the current status and writes an HTML file to kanban-static.html: make run.

The dynamic version runs a web application at http://localhost:15000/kanban.html and updates the GUI via JavaScript automatically using the Web Service: make run-api.

The app version runs a macOS application via make run-app. You can also create a compiled bundle KanbanView.app version that encapsulates the scripts into an easy to use standalone macOS application.

Dark mode with project mode enabled:

Types of tasks:

History of task actions:

Universe view on the projects:

How many minutes are scheduled for today (tags with plain numbers such as 5, 15, 30 are counted) and view tasks in an Eisenhower matrix (tags A, B, C, D are used):

Challenge yourself for 66 days by trying to focus on completing a specific type of tasks (Seinfeld method):

Remote control via iPad:

Commands

After downloading the command line tools or downloading the sources and executing make install, you've the tools things-cli, things-api and things-kanban in your path. Other available make commands are listed by executing make:

$ make
CLI, API and Web Service for Things3.

Configuration:
 * Static Kanban : kanban-static.html
 * Dynamic Kanban: http://localhost:15000/kanban.html

Avaliable environment variables:
 * THINGSDB    - Path to database
 * TAG_WAITING - Tag for tasks you are waiting for
 * TAG_MIT     - Tag for most important tassk

Available commands:
 * run          - Run code in static mode.
 * open         - Open GUI in static mode.
 * run-api      - Run code in api mode.
 * open-api     - Open GUI in api mode in the browser.
 * kill-api     - Kill code in api mode.
 * run-app      - Run code in app mode.
 * cli          - Run code in cli mode (use 'args' for arguments).
 * app          - Create KanbanView App.
 * install      - Install the library and command line tools.
 * uninstall    - Remove the library and command line tools.
 * test         - Run unit tests and test coverage.
 * doc          - Document code (pydoc).
 * clean        - Cleanup (e.g. pyc files).
 * auto-style   - Automatially style code (autopep8).
 * code-style   - Check code style (pycodestyle).
 * code-lint    - Check code lints (pyflakes, pyline, flake8).
 * css-lint     - Check CSS styke lints (csslint).
 * js-lint      - Check JS code lints (jslint).
 * html-lint    - Check HTML file lints (tidy).
 * code-count   - Count code lines (cloc).
 * deps-install - Install dependencies (see requirements.txt).
 * feedback     - Create a GitHub issue.

Command Line Interface (CLI)

The CLI allows you to access the Things3 database via the comand line:

$ things-cli inbox
 -  Inbox Todo  ( None )

It is also possible to get the information formatted as json strings:

$ things-cli --json next | jq
[
  {
    "uuid": "9CD92553-95D7-4CF2-B554-F1DE9F563018",
    "title": "Due Todo",
    "context": "Next Project",
   "context_uuid": "DED787E0-874A-4783-8F0F-0A02F87F8419",
    "due": "2152-08-28"
  },
  {
    "uuid": "4C5D620C-165C-41D2-BC5B-A34065348D92",
    "title": "Today Project Todo",
    "context": "Today Project",
    "context_uuid": "52ADBAB5-A0EC-4D3F-BF83-2D578DAE3AF3",
    "due": null
  },
  {
    "uuid": "2ECBE4AA-2E3F-49CC-AA38-CBFFBFD2B1FD",
    "title": "Todo with Checklist",
    "context": "Next Project",
    "context_uuid": "DED787E0-874A-4783-8F0F-0A02F87F8419",
    "due": null
  },
  {
    "uuid": "709794DA-EB89-4A1B-BBE5-2BF8424BBA28",
    "title": "Waiting for Todo",
    "context": "Next Project",
    "context_uuid": "DED787E0-874A-4783-8F0F-0A02F87F8419",
    "due": null
  }
]

Further, you can export data as csv via $ things-cli --csv all > tasks.csv and import the file into Excel via File > Import > CSV file > Delimited / UTF-8 > Comma:

However, the CLI is only in a beginning state. The original bash based version can be found at another GitHub repo. Overall commands are:

$ things-cli -h
usage: things3_cli.py [-h] [-j] [-c] [--version] command ...

Simple read-only Thing 3 CLI.

positional arguments:
  command         One of the following commands:
    inbox         Shows all inbox tasks
    today         Shows all todays tasks
    upcoming      Shows all upcoming tasks
    next          Shows all next tasks
    someday       Shows all someday tasks
    completed     Shows all completed tasks
    cancelled     Shows all cancelled tasks
    trashed       Shows all trashed tasks
    feedback      Give feedback
    all           Shows all tasks
    csv           Exports all tasks as CSV
    due           Shows all tasks with due dates
    headings      Shows all headings
    hours         Shows how many hours have been planned today
    ical          Shows all tasks ordered by due date as iCal
    logbook       Shows all tasks completed today
    mostClosed    Shows days on which most tasks were closed
    mostCancelled
                  Shows days on which most tasks were cancelled
    mostTrashed   Shows days on which most tasks were trashed
    mostCreated   Shows days on which most tasks were created
    mostTasks     Shows projects that have most tasks
    mostCharacters
                  Shows tasks that have most characters
    nextish       Shows all nextish tasks
    old           Shows all old tasks
    projects      Shows all projects
    repeating     Shows all repeating tasks
    schedule      Schedules an event using a template
    search        Searches for a specific task
    stat          Provides a number of statistics
    statcsv       Exports some statistics as CSV
    subtasks      Shows all subtasks
    tag           Shows all tasks with the waiting for tag
    tags          Shows all tags ordered by their usage
    waiting       Shows all tasks with the waiting for tag

optional arguments:
  -h, --help      show this help message and exit
  -j, --json      output as JSON
  -c, --csv       output as CSV
  --version       show program's version number and exit

Application Programming Interface (API)

The API allows you to access the Things3 todos within other Python scripts:

$ make doc
...
class Things3(builtins.object)
     |  Things3()
     |  
     |  Simple read-only API for Things 3.
     |  
     |  Methods defined here:
     |  
     |  get_anytime(self)
     |      Get anytime tasks.
     |  
     |  get_inbox(self)
     |      Get all tasks from the inbox.
...

Web Service

The web service allows you to access the Things3 database via a web service:

$ make run-server
Starting up...
Serving API at http://localhost:15000/api/{command}

Via curl you can browse the json data via command line:

$ curl -s http://localhost:15000/api/today | jq
[
  {
    "uuid": "D7D879D2-5A2D-48AA-AF8A-AADCEC228D2B",
    "title": "Today Todo",
    "context": "Today Project",
    "context_uuid": "52ADBAB5-A0EC-4D3F-BF83-2D578DAE3AF3",
    "due": null
  }
]

kanbanview's Issues

Different color for upcoming tasks/projects *without* a deadline

Goal

• As a user
• I want to distinguish tasks with a deadline from those without by their color
• so that I can see at a glance which tasks have a deadline.

Suggested approach
In order to achieve this goal I suggest to...
color tasks that are scheduled but do not have a deadline with a different color than tasks with a deadline.
For me personally, green is fine, just like the normal tasks.

Additional information
Right now, in the 'Upcoming' and 'Today' columns all items are red. Which defeats the purpose of making an item red to draw attention to it.

---

As an aside, when thinking about colors:

• Maybe someday task/projects in the Kanban view could be gray?
• In the Eisenhower matrix, the color of the 'A' header could be simply the deadline color. Now it clashes (for my taste) with the deadline color. Some holds true for the color of the 'B' header.

Account for nested tags in Things

Goal

• Allow users of nested tags in Things to define the top-level tag in KanbanView

Example tag hierarchy in Things:

Waiting

Waiting for Bob
Waiting for Tom

• Currently, the Waiting tag must be explicitly added to the task for it to show in the Kansan column
• Currently, tasks tagged “Waiting for Bob” don’t show in the Waiting Kanban column, despite the tag hierarchy

Add support for configuration

Goal

• As a user
• I want to configure e.g. the names of the tags
• so that I don't have to change my workflow

Suggested approach
In order to achieve this goal I suggest to implement a GUI to change some variables

Additional context

• configuration file
• documentation
• GUI

MIT column does not show tasks with user defined tag

To Reproduce

1. In ~/.kanbanviewrc set tag_mit to something else than MIT, e.g. Wichtig.
2. Start or restart Kanbanview.

Expected behavior
Tasks with the user defined tag appear in the 'MIT' column.
(However they don't, and tasks tagged with MIT still appear in it.)

Additional context
Clicking the 'MIT' column opens the correct tag in Things and the tooltip of the column shows the user defined tag. So reading tag_mit from the config file seems successful.

Eisenhower tag does not work

I cannot get any task in the Eisenhower matrix. I have tried using your current tags (A,...D) or the new option in the preference (I am using the official app!).

Eisenhower matrix: tag configuration

What are the settings to get tasks/projects in the Eisenhower matrix in version 2.6.0?

Add support for remote access via iPad

Goal

• As a user
• I want to access KanbanView on the iPad
• so that I'm more mobile

Suggested approach
In order to achieve this goal I suggest to enhance the documentation in order to explain how to do this.

Additional context

• Add configuration to listen on port 0.0.0.0
• Add link to copy public URL
• Add icon for saving the page as a web app
• Test layout on iPadOS
• Fix layout on iPadOS (e.g. replace input selector)

Tasks of "Someday" projects appear in the "Next" column

Hi,
in the "Next" column of the Kanban view, the tasks of projects that are scheduled for "Someday" appear. The tasks themselves are not scheduled for "Someday", however Things treats them as such (when they are not scheduled for a specific day).

edit: Tasks of upcoming projects are also shown in "Next".

Add support for Windows/iOS app including write access

Goal

• As a user
• I want to use KanbanView on multiple devices
• so that I don't need to have/use a mac

Suggested approach
In order to achieve this goal I suggest to use the undocumented remote API instead of direct database access.

Additional context

• Testing the API:

• Running GUI on Windows:

ModuleNotFoundError: No module named 'things'

Hi, I'm running a clean version of python3.9 installed via brew.

after make install, etc and running things-kanban or things-api I get:

File "/usr/local/lib/python3.9/site-packages/things3_api-2.7.0.dev1-py3.9.egg/things3/things3.py", line 18, in
ModuleNotFoundError: No module named 'things'

this, in things3.py, gives me pause

 # the new core library, migration ongoing
 import things

I ran a find and I'm not seeing a things.py

Extracting (not-completed/not trashed) number of tasks for each project

In the following:
SELECT
PROJECT.title,
(SELECT COUNT(uuid) FROM TMTask WHERE project = PROJECT.uuid)
FROM
TMTask as PROJECT
WHERE
PROJECT.type = 1

This extract all tasks even completed ones. Adding more conditions (I tried in both WHERE statements) does not seems to change the count #.

In addition, it would be nice to keep information about the area title (for filtering) so that project level display in the KanbanView is possible.

Add support to export tasks to calendar

Goal

• As a user
• I want to see time related tasks in my calendar
• so that I see them in parallel to items in my calendar

Suggested approach
In order to achieve this goal I suggest to have a button per area/project (or regular export on start)

Additional context

• partly implemented at https://github.com/AlexanderWillner/things.sh

Update README.md

What projects should appear in the "Grooming" column?

@AlexanderWillner wrote:
I added a new column to show empty projects.

I really like the "Grooming" column!
For me it would be useful, if "stalled" projects are shown in the grooming column.
I (and many others) define a stalled project as a project that does not have a next action. Now we need to clarify the next action. For me, a next action is a task that is not scheduled for Someday, i.e. it is either available now or scheduled for a specific date.

@AlexanderWillner wrote:
actually, this is on purpose: imho the project should be scheduled when there is no active task anymore (but only scheduled ones)

This is personal preference. I do not flesh out all tasks of a project. So a project can be active (i.e. if I have time, I take a look at it) without having a task written down that I can do right now.
It is stalled if it has neither an unscheduled or Upcoming task, as nothing will happen if I just look at my tasks. In contrast, a project with an Upcoming task will eventually get moved forward, when the scheduled task appears in my today view.

To filter out projects that have a scheduled task, I added the disjunct OR PROJECT_TASK.{self.IS_SCHEDULED} to the counting part of the "Grooming" query (actually the function is called get_empty_projects ;) ).

This still leaves me with projects, that have recurring tasks in them. I do not want to see those projects in "grooming", as they also get moved forward (and usually are maintenance projects).
When not counting recurring tasks, one needs to be aware of paused recurring tasks and ended recurring tasks, as both are not next tasks according to my and your definition.

I have another disjunct for the counting part in the "Grooming" query to filter recurring tasks that are neither paused nor ended.

RECURRING_IS_NOT_PAUSED = "instanceCreationPaused = 0"
RECURRING_HAS_NEXT_STARTDATE = "nextInstanceStartDate IS NOT NULL"

... OR 
(PROJECT_TASK.{self.IS_RECURRING} AND 
PROJECT_TASK.{self.RECURRING_IS_NOT_PAUSED} AND
PROJECT_TASK.{self.RECURRING_HAS_NEXT_STARTDATE})

edit: exclude recurring tasks that are ended.

Add support for showing tasks in a GANTT

Goal

• As a user
• I want to manage some tasks with time restrictions
• so that I see how tasks are scheduled / planned

Suggested approach
In order to achieve this goal I suggest to show tasks with a start date and due date in a GANTT.

Additional context

• screen shot

Add support to cluster projects in areas

Goal

• As a user
• I want to cluster my projects in areas
• so that there is more structure in my review process

Suggested approach
In order to achieve this goal I suggest to change the navigation bar accordingly.

Additional context
Feedback from Johan

Allow filtering by tag

Goal

• As a user
• I want to be able to view only those tasks in Kanban view with a specific tag
• so that I can focus on those tasks only

Suggested approach
In order to achieve this goal I suggest to replicate the things3 UI where tags to filter by can be chosen at the top of the page

Additional context

• screen shot

My own use case is that I use the same database for work and personal items, with Work and Personal being Areas in Things3. I have Work and Personal tags on the Areas, allowing me (in Things3) to focus on either of these in any of the task lists. Without this, my Kanban view is full of both work and personal tasks.

When an area is selected also show tasks of contained projects

When I select an area in the pane on the left, I want to have an overview of what is going on in that area. For me, that includes the tasks of project that are contained in the area.

Currently, only tasks in the area that do not have a project are shown.

Add support for anaconda (app)

The make app command does not work on my computer (macOS 10.15.4). I have tried both in the regular shell and in the pipenv shell. Both ends with: make: *** [app] Error 1.

Move T/P state to client

Add support for OpenAPI

Goal

• As a developer
• I want to use the API
• so that I can develop features on top of it

Suggested approach
In order to achieve this goal I suggest to follow OpenAPI.

Additional context

• convert current API towards new specification