Parse taskmark-spec markdown files into Python.
pip install taskmarkimporttaskmark# Parse stringstore=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 tasksfortaskinstore:
print(task["title"])
# Check for warningsstore.check() # raises ParseError if any warnings# Access frontmatter (timezone, locale)ifstore.frontmatter:
print(store.frontmatter.timezone) # e.g., "America/New_York"importtaskmarkfromtaskmarkimportTaskChanges, REMOVEstore=taskmark.load("tasks.md")
# Update taskresult=taskmark.update(
store,
title="Build parser",
project="project",
changes=TaskChanges(state="done", priority=REMOVE),
)
# Write changes to disktaskmark.write_updates(store)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:dailySupported 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=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 filetask.inherited_tags# tags from headings| 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) |
| 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 |
| 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 |
See taskmark-spec for format details.
MIT