task-tracker-py 0.1.0__tar.gz

task_tracker_py-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: task-tracker-py
+Version: 0.1.0
+Summary: task-tracker-py: the .tracker/tasks/ format linter and CLI, stdlib only
+Home-page: https://gitlab.com/meehai/task-tracker
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4; extra == "dev"
+
+# task
+
+A CLI for `.tracker/tasks/` task trackers: one dir per task, one `TASK.md` each. **Stdlib only, no
+regular expressions.**
+
+## Format
+
+```
+.tracker/tasks/{open,closed}/<ID>-<slug>/TASK.md   (attachments allowed beside it)
+```
+
+```
+# Task title
+
+**Created**: 2026-04-21
+**Priority**: 2
+**Closed**: n/a
+
+... free form description ...
+```
+
+- The dir is `<ID>-<anything>`; only the ID before the first dash is read (`01-` is ID 1).
+- IDs are integers 1..N, unique across `open/` + `closed/`, no gaps: deleting a task moves the highest-ID
+  task into the hole.
+- The header fields come in any order, each once, followed by an empty line.
+- `**Created**` is an ISO date (or datetime). `**Closed**` is `n/a` in `open/`, and an ISO date no earlier
+  than `**Created**` in `closed/`.
+- `**Priority**` is a positive integer, higher is more urgent.
+- Files directly in `open/` or `closed/` (e.g. `.gitkeep`) are ignored.
+
+`task.Task` is one task, validated in `__post_init__` (wrong type: `TypeError`, bad value: `ValueError`). It can
+be built in memory: its `TASK.md` need not exist, but its `extra_files` must. `task_from_path(task_dir)` reads a
+task dir into a `Task`.
+
+## `task/task.py [--dir <tasks_dir>] {ls,create,check}`
+
+`--dir` defaults to `./.tracker/tasks`. Logs go through `logging`; set `TASK_LOGLEVEL` (default `INFO`).
+
+```bash
+python task/task.py ls                   # open tasks, by priority then ID
+python task/task.py ls --include_closed  # plus closed ones
+python -m task.task -d .tracker/tasks ls # same, via the installed package (`pip install .`)
+```
+
+`check` parses every task (so any format violation raises), then raises `ValueError` on duplicate IDs, an ID
+gap (IDs must be 1..N), or a task whose `**Closed**` does not match its `open/` / `closed/` dir. `create` is
+not implemented yet (task 1).
+
+## Tests
+
+```bash
+python -m pytest test/
+```
+
+One broken rule per case:
+
+- `test/unit/test_task.py` — `Task` field rules, on in-memory tasks.
+- `test/unit/test_task_from_path.py` — the on-disk format: dir name, header, dates, extra files; `main` on a
+  throwaway tracker.
+- `test/unit/test_task_check.py` — `check` in-process (`handle_command`) on in-memory tasks: IDs and
+  open/closed status.
+
+`python test/lint/run_all.py` runs ruff and pylint.
+
+## Acknowledgments
+
+Inspired by tsoding's [tatr](https://github.com/tsoding/tatr): tasks as plain files in the repo, driven by
+a small CLI.

task_tracker_py-0.1.0/README.md

@@ -0,0 +1,68 @@
+# task
+
+A CLI for `.tracker/tasks/` task trackers: one dir per task, one `TASK.md` each. **Stdlib only, no
+regular expressions.**
+
+## Format
+
+```
+.tracker/tasks/{open,closed}/<ID>-<slug>/TASK.md   (attachments allowed beside it)
+```
+
+```
+# Task title
+
+**Created**: 2026-04-21
+**Priority**: 2
+**Closed**: n/a
+
+... free form description ...
+```
+
+- The dir is `<ID>-<anything>`; only the ID before the first dash is read (`01-` is ID 1).
+- IDs are integers 1..N, unique across `open/` + `closed/`, no gaps: deleting a task moves the highest-ID
+  task into the hole.
+- The header fields come in any order, each once, followed by an empty line.
+- `**Created**` is an ISO date (or datetime). `**Closed**` is `n/a` in `open/`, and an ISO date no earlier
+  than `**Created**` in `closed/`.
+- `**Priority**` is a positive integer, higher is more urgent.
+- Files directly in `open/` or `closed/` (e.g. `.gitkeep`) are ignored.
+
+`task.Task` is one task, validated in `__post_init__` (wrong type: `TypeError`, bad value: `ValueError`). It can
+be built in memory: its `TASK.md` need not exist, but its `extra_files` must. `task_from_path(task_dir)` reads a
+task dir into a `Task`.
+
+## `task/task.py [--dir <tasks_dir>] {ls,create,check}`
+
+`--dir` defaults to `./.tracker/tasks`. Logs go through `logging`; set `TASK_LOGLEVEL` (default `INFO`).
+
+```bash
+python task/task.py ls                   # open tasks, by priority then ID
+python task/task.py ls --include_closed  # plus closed ones
+python -m task.task -d .tracker/tasks ls # same, via the installed package (`pip install .`)
+```
+
+`check` parses every task (so any format violation raises), then raises `ValueError` on duplicate IDs, an ID
+gap (IDs must be 1..N), or a task whose `**Closed**` does not match its `open/` / `closed/` dir. `create` is
+not implemented yet (task 1).
+
+## Tests
+
+```bash
+python -m pytest test/
+```
+
+One broken rule per case:
+
+- `test/unit/test_task.py` — `Task` field rules, on in-memory tasks.
+- `test/unit/test_task_from_path.py` — the on-disk format: dir name, header, dates, extra files; `main` on a
+  throwaway tracker.
+- `test/unit/test_task_check.py` — `check` in-process (`handle_command`) on in-memory tasks: IDs and
+  open/closed status.
+
+`python test/lint/run_all.py` runs ruff and pylint.
+
+## Acknowledgments
+
+Inspired by tsoding's [tatr](https://github.com/tsoding/tatr): tasks as plain files in the repo, driven by
+a small CLI.

task_tracker_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

task_tracker_py-0.1.0/setup.py

@@ -0,0 +1,32 @@
+"""setup.py -- note use setuptools==73.0.1; older versions fuck up the data files, newer versions include resources."""
+from pathlib import Path
+from setuptools import setup, find_packages
+
+NAME = "task-tracker-py"
+VERSION = "0.1.0"
+DESCRIPTION = "task-tracker-py: the .tracker/tasks/ format linter and CLI, stdlib only"
+URL = "https://gitlab.com/meehai/task-tracker"
+
+CWD = Path(__file__).absolute().parent
+with open(CWD / "README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+REQUIRED_DEV = [
+    "pytest>=8.4",
+]
+
+setup(
+    name=NAME,
+    version=VERSION,
+    description=DESCRIPTION,
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url=URL,
+    packages=find_packages(exclude=["test", "test.*"]),
+    install_requires=[], # no dependencies, just stdlib
+    extras_require={"dev": REQUIRED_DEV},
+    dependency_links=[],
+    license="MIT",
+    python_requires=">=3.11",
+    scripts=[],
+)

task_tracker_py-0.1.0/task/__init__.py

@@ -0,0 +1,7 @@
+"""task - the `.tracker/tasks/` tooling for this repo and the libraries vendored beside it.
+
+Stdlib only, no third-party deps, and no regular expressions: the two formats here (a task's header
+field, a task dir name) are parsed by hand so the accepted grammar is visible in the code.
+
+Today it ships `check_tasks`; the `task` CLI grows beside it (task-tracker #1).
+"""

task_tracker_py-0.1.0/task/task.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""task.py
+CLI for integrating with the task manager. Inspired by tsoding's tatr.
+Tasks follows this format: tasks/open/ID-name/TASK.md file.
+IDs are contiguous integers starting from 1.
+
+Task header:
+```
+# Task title
+
+**Created**: 2026-04-21
+**Priority**: 2
+**Closed**: n/a
+
+... free form description ...
+```
+"""
+from __future__ import annotations
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+from dataclasses import dataclass, field
+from datetime import datetime
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+MAX_TASK_ID = 1_000_000
+COMMANDS = {"ls", "create", "check", "close"}
+
+@dataclass
+class Task:
+    """The task dataclass representing the in-memory object of a TASK.md file"""
+    task_path: Path                                       # Path to TASK.md. For in-memory tasks (tests) can be missing
+    task_id: int                                          # Task ids are positive integers (and contiguous)
+    task_name: str                                        # The task name as defined in the TASK.md file
+    created_at: datetime                                  # Datetime when the task was created
+    priority: int                                         # Priority of the task. Positive integer. Higher is better
+    description: str                                      # Textual description of the task in the TASK.md file
+    closed_at: datetime | str = "n/a"                     # When the task was closed, if any
+    extra_files: list[Path] = field(default_factory=list) # Extra files in the directory where TASK.md is defined
+
+    def __post_init__(self):
+        if not isinstance(self.task_path, Path):
+            raise TypeError(f"Task path must be a path: {self.task_path}")
+        if self.task_path.name != "TASK.md":
+            raise ValueError(f"Task path must point to a TASK.md file: {self.task_path}")
+        if not isinstance(self.task_id, int):
+            raise TypeError(f"{self.task_path} - Task id must be an integer, got: {self.task_id}")
+        if not 0 < self.task_id < MAX_TASK_ID:
+            raise ValueError(f"{self.task_path} - Task id must be as positive integer, got: {self.task_id}")
+        if not isinstance(self.task_name, str):
+            raise TypeError(f"{self.task_path} - The task name must be a string, got: {self.task_name}")
+        if len(self.task_name) == 0:
+            raise ValueError(f"{self.task_path} - The task name cannot be empty")
+        if not isinstance(self.created_at, datetime):
+            raise TypeError(f"{self.task_path} - created_at must be datetime, got {self.created_at}")
+        if not isinstance(self.priority, int):
+            raise TypeError(f"{self.task_path} - The priority must be an integer: {self.priority}")
+        if self.priority <= 0:
+            raise ValueError(f"{self.task_path} - The priority must be positive: {self.priority}")
+        if not isinstance(self.closed_at, datetime) and self.closed_at != "n/a":
+            raise TypeError(f"{self.task_path} - closed_at must be datetime or 'n/a', got {self.closed_at}")
+        if isinstance(self.closed_at, datetime) and self.closed_at < self.created_at:
+            raise ValueError(f"{self.task_path} - Task closed before it was opened: {self.closed_at} {self.created_at}")
+        if not isinstance(self.description, str):
+            raise TypeError(f"{self.task_path} - description must be a free-form text, got: {self.description}")
+        if not isinstance(self.extra_files, list) or not all(isinstance(x, Path) for x in self.extra_files):
+            raise TypeError(f"{self.task_path} - extra files must be a list of paths: {self.extra_files}")
+        if any(not x.exists() for x in self.extra_files):
+            raise FileNotFoundError(f"{self.task_path} - one or more extra files does not exist: {self.extra_files}")
+
+    @property
+    def is_open(self) -> bool:
+        """Returns true if the task is open, false otherwise. Uses closed_at as reference."""
+        return self.closed_at == "n/a"
+
+def task_from_path(task_dir: Path) -> Task:
+    """Creates a task from a file path, e.g. a single TASK.md"""
+    if not (task_file := task_dir / "TASK.md").exists():
+        raise FileNotFoundError(f"Task file does not exist in '{task_file}'")
+    with open(task_file, "r", encoding="utf-8") as fp:
+        lines = fp.readlines()
+    extra_files: list[Path] = [f for f in task_dir.iterdir() if f.is_file() and f.name != "TASK.md"]
+
+    task_id = int(task_dir.name.split("-")[0])
+    created_at, priority, description, closed_at = None, None, None, None
+
+    if len(lines) == 0 or not lines[0].startswith("# "):
+        raise ValueError(f"'task_name' is not the first line: {lines} {task_file=}")
+    task_name = lines[0][2:-1] # Get rid of '# ' and \n
+
+    n_lines_read = 1
+    try:
+        for line in map(lambda x: x.strip(), lines[1:]):
+            if created_at is not None and priority is not None and closed_at is not None:
+                break
+            n_lines_read += 1
+            if line == "":
+                continue
+            if line.startswith("**Created**"):
+                if created_at is not None:
+                    raise ValueError(f"'Created' was already set: {created_at} {task_file=}")
+                created_at = datetime.fromisoformat(line[13:])
+            elif line.startswith("**Priority**"):
+                if priority is not None:
+                    raise ValueError(f"'Priority' was already set: {priority} {task_file=}")
+                priority = int(line[13:])
+            elif line.startswith("**Closed**"):
+                if closed_at is not None:
+                    raise ValueError(f"'Closed' was already set: {closed_at} {task_file=}")
+                closed_at = line[12:] if line[12:] == "n/a" else datetime.fromisoformat(line[12:])
+    except (TypeError, ValueError) as e:
+        raise type(e)(f"{task_file=} {e}") from e
+
+    if created_at is None or priority is None or closed_at is None:
+        raise ValueError(f"Header is invalid: {task_file=}. One is missing: {created_at=} {priority=} {closed_at=}")
+
+    if len(lines) > n_lines_read and lines[n_lines_read] != "\n":
+        raise ValueError(f"Expected empty line, got: {lines[n_lines_read]!r} ({task_file=})")
+
+    description = "".join(lines[n_lines_read:])
+    return Task(task_file, task_id, task_name, created_at, priority, description, closed_at, extra_files)
+
+def _print_table(tasks: list[Task]):
+    header = ("ID", "Name", "Priority", "Created")
+    rows = []
+    for t in tasks:
+        t_name = f"{t.task_name[0:78]}.." if len(t.task_name) > 80 else t.task_name
+        rows.append((str(t.task_id), t_name, str(t.priority), t.created_at.date().isoformat()))
+    widths = [max(len(row[i]) for row in [header, *rows]) for i in range(len(header))]
+    for row in [header, tuple("-" * w for w in widths), *rows]:
+        print("  ".join(cell.ljust(w) for cell, w in zip(row, widths)))
+
+def handle_command(args: Namespace, open_tasks: list[Task], closed_tasks: list[Task]):
+    """Handles a command. Different function than main, so we can test with in-memory tasks."""
+    if args.command == "ls":
+        print("== Open tasks ==")
+        _print_table(sorted(open_tasks, key=lambda t: (-t.priority, t.task_id)))
+        if args.include_closed:
+            print("\n== Closed tasks ==")
+            _print_table(closed_tasks)
+
+    if args.command == "create":
+        raise NotImplementedError(args.command)
+
+    if args.command == "check":
+        # IDs are unique across open/ + closed/ and contiguous 1..N
+        ids = [t.task_id for t in [*open_tasks, *closed_tasks]]
+        if dups := sorted({i for i in ids if ids.count(i) > 1}):
+            raise ValueError(f"Duplicate ids: {dups}")
+        if missing := sorted(set(range(1, max(ids, default=0) + 1)) - set(ids)):
+            raise ValueError(f"There are gaps in the ids. First missing: {missing[0]}. All missing: {missing}")
+
+        # Check that closed_at is respected in a task being open/closed
+        for task in open_tasks:
+            if not task.is_open:
+                raise ValueError(f"Task {task.task_path.resolve()} is in open/ folder, but should be in closed/")
+        for task in closed_tasks:
+            if task.is_open:
+                raise ValueError(f"Task {task.task_path.resolve()} is in closed/ folder, but should be in open/")
+
+        logger.info(f"Task format OK ({len(ids)} tasks)")
+
+    if args.command == "close":
+        raise NotImplementedError(args.command)
+
+def main(args: Namespace):
+    """main fn"""
+    logger.debug(f"Reading tasks from '{args.dir}'")
+
+    if sorted([f.name for f in args.dir.iterdir()]) != ["closed", "open"]:
+        raise ValueError(f"Wrong tasks dir: {args.dir}")
+    open_tasks = [task_from_path(pth) for pth in (args.dir / "open").iterdir() if pth.is_dir()]
+    closed_tasks = [task_from_path(pth) for pth in (args.dir / "closed").iterdir() if pth.is_dir()]
+
+    logger.debug(f"Read {len(open_tasks)} open tasks and {len(closed_tasks)} closed tasks")
+    handle_command(args, open_tasks, closed_tasks)
+
+if __name__ == "__main__":
+    level_name = os.environ.get("TASK_LOGLEVEL", "INFO").upper()
+    logging.basicConfig(level=level_name, format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s")
+
+    parser = ArgumentParser()
+    parser.add_argument("--dir", "-d", type=Path, help="Path to the tasks dir", default=Path.cwd() / ".tracker/tasks")
+    parser.add_argument("command", choices=COMMANDS, help="The command you want to run with the tasks (e.g. ls)")
+    parser.add_argument("--include_closed", "-c", action="store_true", help="Include closed when listing tasks (ls)")
+    arg = parser.parse_args()
+    main(arg)

task_tracker_py-0.1.0/task_tracker_py.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: task-tracker-py
+Version: 0.1.0
+Summary: task-tracker-py: the .tracker/tasks/ format linter and CLI, stdlib only
+Home-page: https://gitlab.com/meehai/task-tracker
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4; extra == "dev"
+
+# task
+
+A CLI for `.tracker/tasks/` task trackers: one dir per task, one `TASK.md` each. **Stdlib only, no
+regular expressions.**
+
+## Format
+
+```
+.tracker/tasks/{open,closed}/<ID>-<slug>/TASK.md   (attachments allowed beside it)
+```
+
+```
+# Task title
+
+**Created**: 2026-04-21
+**Priority**: 2
+**Closed**: n/a
+
+... free form description ...
+```
+
+- The dir is `<ID>-<anything>`; only the ID before the first dash is read (`01-` is ID 1).
+- IDs are integers 1..N, unique across `open/` + `closed/`, no gaps: deleting a task moves the highest-ID
+  task into the hole.
+- The header fields come in any order, each once, followed by an empty line.
+- `**Created**` is an ISO date (or datetime). `**Closed**` is `n/a` in `open/`, and an ISO date no earlier
+  than `**Created**` in `closed/`.
+- `**Priority**` is a positive integer, higher is more urgent.
+- Files directly in `open/` or `closed/` (e.g. `.gitkeep`) are ignored.
+
+`task.Task` is one task, validated in `__post_init__` (wrong type: `TypeError`, bad value: `ValueError`). It can
+be built in memory: its `TASK.md` need not exist, but its `extra_files` must. `task_from_path(task_dir)` reads a
+task dir into a `Task`.
+
+## `task/task.py [--dir <tasks_dir>] {ls,create,check}`
+
+`--dir` defaults to `./.tracker/tasks`. Logs go through `logging`; set `TASK_LOGLEVEL` (default `INFO`).
+
+```bash
+python task/task.py ls                   # open tasks, by priority then ID
+python task/task.py ls --include_closed  # plus closed ones
+python -m task.task -d .tracker/tasks ls # same, via the installed package (`pip install .`)
+```
+
+`check` parses every task (so any format violation raises), then raises `ValueError` on duplicate IDs, an ID
+gap (IDs must be 1..N), or a task whose `**Closed**` does not match its `open/` / `closed/` dir. `create` is
+not implemented yet (task 1).
+
+## Tests
+
+```bash
+python -m pytest test/
+```
+
+One broken rule per case:
+
+- `test/unit/test_task.py` — `Task` field rules, on in-memory tasks.
+- `test/unit/test_task_from_path.py` — the on-disk format: dir name, header, dates, extra files; `main` on a
+  throwaway tracker.
+- `test/unit/test_task_check.py` — `check` in-process (`handle_command`) on in-memory tasks: IDs and
+  open/closed status.
+
+`python test/lint/run_all.py` runs ruff and pylint.
+
+## Acknowledgments
+
+Inspired by tsoding's [tatr](https://github.com/tsoding/tatr): tasks as plain files in the repo, driven by
+a small CLI.

task_tracker_py-0.1.0/task_tracker_py.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+setup.py
+task/__init__.py
+task/task.py
+task_tracker_py.egg-info/PKG-INFO
+task_tracker_py.egg-info/SOURCES.txt
+task_tracker_py.egg-info/dependency_links.txt
+task_tracker_py.egg-info/requires.txt
+task_tracker_py.egg-info/top_level.txt

task_tracker_py-0.1.0/task_tracker_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

task_tracker_py-0.1.0/task_tracker_py.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8.4

task_tracker_py-0.1.0/task_tracker_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+task