taskmark

Parse taskmark-spec markdown files into Python.

Installation

pip install taskmark

Parse

import taskmark

# Parse string
store = taskmark.loads("""
# TODO +project

## Features

- [ ] (A) Build parser @alice #urgent due:2024-03-15 ~2h
  - [ ] Write tests
  - [ ] Document API
- [ ] Weekly review planned:2024-03-15 repeat:weekly
""")

# Parse file (follows [text](file.md) links)
store = taskmark.load("path/to/todo.md")

# Iterate tasks
for task in store:
    print(task["title"])

# Check for warnings
store.check()  # raises ParseError if any warnings

# Access frontmatter (timezone, locale)
if store.frontmatter:
    print(store.frontmatter.timezone)  # e.g., "America/New_York"

Mutate

import taskmark
from taskmark import TaskChanges, REMOVE

store = taskmark.load("tasks.md")

# Update task
result = taskmark.update(
    store,
    title="Build parser",
    project="project",
    changes=TaskChanges(state="done", priority=REMOVE),
)

# Write changes to disk
taskmark.write_updates(store)

Recurrence

When a recurring task is marked done, a new task is automatically created for the next occurrence:

# Input: - [ ] Standup planned:2024-03-15 repeat:daily
# After marking done:
# - [x] 2024-03-15 Standup planned:2024-03-15
# - [ ] Standup planned:2024-03-16 repeat:daily

Supported patterns:

• Simple: daily, weekly, monthly, yearly
• Multiplied: 2weeks, 3days, 2months, 2d, 3w
• Day of month: 15th, 1st, 31st (clamps to month end)
• Nth weekday: 2nd-tuesday, last-friday, 1st-monday
• Natural language: "every other week", "every 2 weeks" (requires quotes for spaces)

Task Access

task = store[0]

# Dict access (content fields)
task["title"]           # "Build parser"
task["state"]           # "open"
task["priority"]        # "A"
dict(task)              # all content fields

# Attribute access (all fields)
task.title              # same as task["title"]
task.file               # Path to source file
task.inherited_tags     # tags from headings

Date Fields

Field	Description
due_date	When task is due
planned_date	When task is planned to start
done_date	When task was completed (auto-set)
created_date	When task was created
started_date	When task was started
paused_date	When task was blocked (auto-set)

API

Function	Input	Output
loads(s)	Markdown string	TaskStore
load(fp)	File path/object	TaskStore
update(store, title, project, changes)	Task identifier + changes	UpdateResult
batch_update(store, updates)	List of updates	BatchUpdateResult
write_updates(store)	Store with changes	WriteResult

Types

Type	Purpose
Task	Dict-like task with attribute access
TaskStore	Iterable collection with warnings and frontmatter
TaskChanges	Changes for update()
Frontmatter	File-level metadata (timezone, locale)
REMOVE	Sentinel to remove field
ParseError	Raised by check()
UpdateResult	Result of single update with status
BatchUpdateResult	Result of batch update
WriteResult	Result of writing updates to files
TaskUpdateSpec	Specification for batch updates
RejectedChange	Details of a rejected change
FileInfo	Source file metadata
Warning	Parse warning details
TaskState	Enum: open, done, cancelled, blocked
UpdateStatus	Enum: updated, not_found, etc.
StateMachine	Customizable state transition machine
StateTransition	Single state transition definition
DEFAULT_STATE_MACHINE	Default state machine instance

Spec

See taskmark-spec for format details.

License

MIT