Skip to content

Latest commit

 

History

History
104 lines (83 loc) · 2.82 KB

AGENTS.md

File metadata and controls

104 lines (83 loc) · 2.82 KB

taskmark

Python parser for taskmark-spec markdown files.

API

Parse

import taskmark

store = taskmark.loads(markdown_string)  # parse string
store = taskmark.load(path_or_file)      # parse file, follows links

Mutate

result = taskmark.update(store, title, project, changes)
write_result = taskmark.write_updates(store)

Types

Type Purpose
Task Dict-like task with attribute access
TaskStore Parse result: tasks, warnings, files
TaskChanges Changes to apply via update()
UpdateResult Result of update()
Frontmatter File-level metadata (timezone, locale)
REMOVE Sentinel to remove field

Task Schema

Field Type Dict Attr
state str Y Y
title str Y Y
priority str | None Y Y
due_date str | None Y Y
planned_date str | None Y Y
done_date str | None Y Y
estimate_minutes int | None Y Y
recurrence str | None Y Y
assignees list[str] Y Y
tags list[str] Y Y
project_path str | None Y Y
custom_fields dict[str, str] Y Y
subtasks list[Task] Y Y
file Path | None N Y
line int | None N Y
explicit_* varies N Y
inherited_* varies N Y

Inheritance

Metadata Heading → Task Parent → Subtask
Projects Join with / Inherit (no override)
Tags Union Union
Assignees Union Union
Custom fields Child overrides Child overrides

Project Structure

src/taskmark/
├── __init__.py      # Public API
├── _parser.py       # Lark parser
├── _transformer.py  # Parse tree → objects
├── _resolver.py     # Inheritance resolution
├── _loader.py       # Multi-file loading
├── _mutator.py      # Task mutation
├── _recurrence.py   # Recurrence pattern calculation
├── _dates.py        # Pendulum date utilities
├── _writer.py       # File writing
├── _types.py        # Type definitions
└── grammar.lark     # Lark grammar

Tests

tests/
├── golden/
│   ├── parse/       # 74 parse tests
│   └── mutate/      # 47 mutation tests
├── test_golden.py   # Golden test runner
└── test_serialization.py

Development

.venv/bin/python -m pytest tests/ -v --no-cov  # run tests
.venv/bin/python -m ruff check src/ tests/     # lint
.venv/bin/python -m mypy src/                  # typecheck

Standards