tsk-todo 0.1.0__tar.gz

tsk_todo-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: tsk-todo
+Version: 0.1.0
+Summary: Minimal todo CLI for the terminal. Pure Python, zero dependencies.
+Keywords: cli,todo,task,task-manager,productivity,terminal,gtd
+Author: michaelrbarley
+Author-email: michaelrbarley <301309661+michaelrbarley@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/michaelrbarley/tsk-todo
+Project-URL: Source, https://github.com/michaelrbarley/tsk-todo
+Project-URL: Issues, https://github.com/michaelrbarley/tsk-todo/issues
+Description-Content-Type: text/markdown
+
+# tsk
+
+A small task manager for the terminal.
+
+```
+$ tsk add water the plants @home +garden due:tomorrow every:weekly
+added 1: water the plants
+
+$ tsk add fix the login bug @work +urgent due:yesterday p:h
+added 2: fix the login bug
+
+$ tsk
+2  H  yesterday  fix the login bug @work +urgent
+1     tomorrow   water the plants @home +garden every:weekly
+```
+
+No daemon, no config file, no dependencies. Your tasks live in one JSON file you can read.
+
+## Install
+
+Needs Python 3.11 or newer.
+
+```
+git clone https://github.com/michaelrbarley/tsk-todo
+cd tsk-todo
+uv tool install .
+```
+
+The command is `tsk`. The package is `tsk-todo`, because `tsk` on PyPI belongs to something else.
+
+Or run it from the clone without installing anything:
+
+```
+uv run tsk
+```
+
+## The idea
+
+You type what you mean and `tsk` works out which parts are metadata:
+
+```
+tsk add renew the passport @admin +boring due:eom p:h
+```
+
+`@admin` is the project, `+boring` is a tag, `due:eom` is the end of this month, `p:h` is high
+priority. Everything left over is the task itself.
+
+Only `due:`, `p:` and `every:` are read as attributes, so ordinary text stays ordinary:
+
+```
+$ tsk add email bob@example.com about the invoice
+$ tsk add fix the -v flag
+$ tsk add ticket: replace the boiler
+```
+
+None of those pick up a project, a tag or an attribute. If it is not a form `tsk` knows, it is
+part of the description.
+
+## Commands
+
+```
+tsk                        list pending tasks
+tsk add <text> [attrs]     add a task
+tsk done <id>...           complete tasks
+tsk rm <id>...             delete tasks
+tsk edit <id> <attrs>      change a task
+tsk note <id> <text>       attach a note
+tsk show <id>              show one task in full
+tsk list [filters]         list tasks
+```
+
+`tsk 3` on its own is shorthand for `tsk show 3`.
+
+`done` and `rm` take several ids at once: `tsk done 2 5 9`.
+
+## Attributes
+
+Use these when adding or editing.
+
+```
+@project      set the project
++tag          add a tag
+-tag          remove a tag, when editing
+due:<when>    set a due date
+p:h|m|l       set priority, high medium or low
+every:<how>   reschedule on completion
+```
+
+Priority also accepts the full word, so `p:high` and `p:h` are the same.
+
+Editing changes only what you name. Everything else is left alone.
+
+```
+$ tsk edit 3 due:friday +urgent
+updated 3: read the book
+```
+
+To clear something, give it no value:
+
+```
+$ tsk edit 3 due: p: every:
+```
+
+A bare `@` clears the project. A leading `-` removes a tag.
+
+## Filters
+
+```
+tsk +garden              tagged garden
+tsk -work                not tagged work
+tsk @home                in the home project
+tsk overdue              past due
+tsk due:friday           due on or before friday
+tsk done                 completed tasks
+tsk all                  everything
+tsk plants               search descriptions and notes
+```
+
+Filters combine, and `list` is optional:
+
+```
+$ tsk @home +garden overdue
+$ tsk list @work due:eow
+```
+
+Bare words search. `tsk list dentist` finds anything with dentist in the description or in a note.
+
+## Dates
+
+Anywhere a date is wanted:
+
+```
+today, tomorrow, yesterday
+monday .. sunday, or mon .. sun
+3d, 2w, 1m, 1y
+eow, eom, eoy
+2026-08-01
+```
+
+Weekday names mean the next one coming. On a Thursday, `due:thursday` is a week away, not today.
+
+Month and year offsets land on a real date. `1m` from the 31st of January is the 28th of February,
+not the 3rd of March.
+
+Due dates are plain calendar dates. `due:friday` means Friday wherever you happen to be, and it
+does not drift when you cross a timezone.
+
+## Repeats
+
+```
+every:daily
+every:weekdays
+every:weekly
+every:monthly
+every:yearly
+```
+
+A repeating task needs a due date. When you complete it, the next one is created for you:
+
+```
+$ tsk done 1
+done 1: water the plants
+  repeats as 5, due in 1 week
+```
+
+The next date is worked out from the old due date, then rolled forward until it is in the future.
+Finish a daily task five days late and the next one is due tomorrow, not last week. You never come
+back to a pile of overdue copies.
+
+Notes do not carry over. The completed task keeps them.
+
+## Notes
+
+```
+$ tsk note 3 the ferns look worse than the rest
+noted on 3: water the plants
+```
+
+Tasks with notes are marked with a `*` in the list. `tsk show 3` prints them.
+
+## Ordering
+
+Tasks sort by due date, then priority, then id. That is the whole rule. Nothing is scored or
+weighted behind your back, so the order is always one you can predict and explain.
+
+Undated tasks sort last. They are not urgent, they are just there.
+
+## Your data
+
+One JSON file, at `~/.local/share/tsk/tasks.json` unless you say otherwise:
+
+```json
+{
+  "version": 1,
+  "issued": 7,
+  "tasks": [
+    {
+      "id": 2,
+      "description": "fix the login bug",
+      "status": "pending",
+      "created": "2026-07-16T14:49:48+00:00",
+      "project": "work",
+      "tags": ["urgent"],
+      "due": "2026-07-15",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+Set `TSK_DATA` to put it somewhere else, or `XDG_DATA_HOME` to move the lot. Keep it in a git repo
+if you want history. Tags are written in a fixed order and absent fields are left out, so diffs
+stay small.
+
+Writes are atomic. The file is written beside itself and then moved into place, so an interrupted
+write cannot leave you with half a file. Existing permissions are preserved.
+
+Ids are never reused. Once id 3 has been handed out, no later task gets it, even if you delete task
+3 the same day. The id you read a minute ago is still the task you thought it was.
+
+## Colour
+
+On when writing to a terminal, off when piped. Set `NO_COLOR` to turn it off entirely.
+
+Overdue is red, due today is yellow, projects are cyan, tags are magenta.
+
+## What it does not do
+
+There is no urgency score, no dependency graph, no user defined attributes, no hooks, no custom
+report definitions and no sync. Each of those either failed the question "would I miss this" or
+costs far more than it returns for a tool this size.
+
+If you want a task on the calendar, `due:` is where it goes. If you want to find it later, tag it.
+That is most of task management.
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+uv run mypy
+```
+
+The suite runs in well under a second. It is worth keeping it that way.
+
+## Licence
+
+MIT

tsk_todo-0.1.0/README.md

@@ -0,0 +1,250 @@
+# tsk
+
+A small task manager for the terminal.
+
+```
+$ tsk add water the plants @home +garden due:tomorrow every:weekly
+added 1: water the plants
+
+$ tsk add fix the login bug @work +urgent due:yesterday p:h
+added 2: fix the login bug
+
+$ tsk
+2  H  yesterday  fix the login bug @work +urgent
+1     tomorrow   water the plants @home +garden every:weekly
+```
+
+No daemon, no config file, no dependencies. Your tasks live in one JSON file you can read.
+
+## Install
+
+Needs Python 3.11 or newer.
+
+```
+git clone https://github.com/michaelrbarley/tsk-todo
+cd tsk-todo
+uv tool install .
+```
+
+The command is `tsk`. The package is `tsk-todo`, because `tsk` on PyPI belongs to something else.
+
+Or run it from the clone without installing anything:
+
+```
+uv run tsk
+```
+
+## The idea
+
+You type what you mean and `tsk` works out which parts are metadata:
+
+```
+tsk add renew the passport @admin +boring due:eom p:h
+```
+
+`@admin` is the project, `+boring` is a tag, `due:eom` is the end of this month, `p:h` is high
+priority. Everything left over is the task itself.
+
+Only `due:`, `p:` and `every:` are read as attributes, so ordinary text stays ordinary:
+
+```
+$ tsk add email bob@example.com about the invoice
+$ tsk add fix the -v flag
+$ tsk add ticket: replace the boiler
+```
+
+None of those pick up a project, a tag or an attribute. If it is not a form `tsk` knows, it is
+part of the description.
+
+## Commands
+
+```
+tsk                        list pending tasks
+tsk add <text> [attrs]     add a task
+tsk done <id>...           complete tasks
+tsk rm <id>...             delete tasks
+tsk edit <id> <attrs>      change a task
+tsk note <id> <text>       attach a note
+tsk show <id>              show one task in full
+tsk list [filters]         list tasks
+```
+
+`tsk 3` on its own is shorthand for `tsk show 3`.
+
+`done` and `rm` take several ids at once: `tsk done 2 5 9`.
+
+## Attributes
+
+Use these when adding or editing.
+
+```
+@project      set the project
++tag          add a tag
+-tag          remove a tag, when editing
+due:<when>    set a due date
+p:h|m|l       set priority, high medium or low
+every:<how>   reschedule on completion
+```
+
+Priority also accepts the full word, so `p:high` and `p:h` are the same.
+
+Editing changes only what you name. Everything else is left alone.
+
+```
+$ tsk edit 3 due:friday +urgent
+updated 3: read the book
+```
+
+To clear something, give it no value:
+
+```
+$ tsk edit 3 due: p: every:
+```
+
+A bare `@` clears the project. A leading `-` removes a tag.
+
+## Filters
+
+```
+tsk +garden              tagged garden
+tsk -work                not tagged work
+tsk @home                in the home project
+tsk overdue              past due
+tsk due:friday           due on or before friday
+tsk done                 completed tasks
+tsk all                  everything
+tsk plants               search descriptions and notes
+```
+
+Filters combine, and `list` is optional:
+
+```
+$ tsk @home +garden overdue
+$ tsk list @work due:eow
+```
+
+Bare words search. `tsk list dentist` finds anything with dentist in the description or in a note.
+
+## Dates
+
+Anywhere a date is wanted:
+
+```
+today, tomorrow, yesterday
+monday .. sunday, or mon .. sun
+3d, 2w, 1m, 1y
+eow, eom, eoy
+2026-08-01
+```
+
+Weekday names mean the next one coming. On a Thursday, `due:thursday` is a week away, not today.
+
+Month and year offsets land on a real date. `1m` from the 31st of January is the 28th of February,
+not the 3rd of March.
+
+Due dates are plain calendar dates. `due:friday` means Friday wherever you happen to be, and it
+does not drift when you cross a timezone.
+
+## Repeats
+
+```
+every:daily
+every:weekdays
+every:weekly
+every:monthly
+every:yearly
+```
+
+A repeating task needs a due date. When you complete it, the next one is created for you:
+
+```
+$ tsk done 1
+done 1: water the plants
+  repeats as 5, due in 1 week
+```
+
+The next date is worked out from the old due date, then rolled forward until it is in the future.
+Finish a daily task five days late and the next one is due tomorrow, not last week. You never come
+back to a pile of overdue copies.
+
+Notes do not carry over. The completed task keeps them.
+
+## Notes
+
+```
+$ tsk note 3 the ferns look worse than the rest
+noted on 3: water the plants
+```
+
+Tasks with notes are marked with a `*` in the list. `tsk show 3` prints them.
+
+## Ordering
+
+Tasks sort by due date, then priority, then id. That is the whole rule. Nothing is scored or
+weighted behind your back, so the order is always one you can predict and explain.
+
+Undated tasks sort last. They are not urgent, they are just there.
+
+## Your data
+
+One JSON file, at `~/.local/share/tsk/tasks.json` unless you say otherwise:
+
+```json
+{
+  "version": 1,
+  "issued": 7,
+  "tasks": [
+    {
+      "id": 2,
+      "description": "fix the login bug",
+      "status": "pending",
+      "created": "2026-07-16T14:49:48+00:00",
+      "project": "work",
+      "tags": ["urgent"],
+      "due": "2026-07-15",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+Set `TSK_DATA` to put it somewhere else, or `XDG_DATA_HOME` to move the lot. Keep it in a git repo
+if you want history. Tags are written in a fixed order and absent fields are left out, so diffs
+stay small.
+
+Writes are atomic. The file is written beside itself and then moved into place, so an interrupted
+write cannot leave you with half a file. Existing permissions are preserved.
+
+Ids are never reused. Once id 3 has been handed out, no later task gets it, even if you delete task
+3 the same day. The id you read a minute ago is still the task you thought it was.
+
+## Colour
+
+On when writing to a terminal, off when piped. Set `NO_COLOR` to turn it off entirely.
+
+Overdue is red, due today is yellow, projects are cyan, tags are magenta.
+
+## What it does not do
+
+There is no urgency score, no dependency graph, no user defined attributes, no hooks, no custom
+report definitions and no sync. Each of those either failed the question "would I miss this" or
+costs far more than it returns for a tool this size.
+
+If you want a task on the calendar, `due:` is where it goes. If you want to find it later, tag it.
+That is most of task management.
+
+## Development
+
+```
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+uv run mypy
+```
+
+The suite runs in well under a second. It is worth keeping it that way.
+
+## Licence
+
+MIT

tsk_todo-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "tsk-todo"
+version = "0.1.0"
+description = "Minimal todo CLI for the terminal. Pure Python, zero dependencies."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "michaelrbarley", email = "301309661+michaelrbarley@users.noreply.github.com" }
+]
+keywords = ["cli", "todo", "task", "task-manager", "productivity", "terminal", "gtd"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/michaelrbarley/tsk-todo"
+Source = "https://github.com/michaelrbarley/tsk-todo"
+Issues = "https://github.com/michaelrbarley/tsk-todo/issues"
+
+[project.scripts]
+tsk = "tsk.cli:main"
+
+[tool.uv.build-backend]
+module-name = "tsk"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1", "pytest-cov>=7.1", "ruff>=0.15,<0.16", "mypy>=2.3"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "PTH", "RUF"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config -ra"
+filterwarnings = ["error"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true