whatnext 0.0.1__tar.gz

whatnext-0.0.1/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mark Norman Francis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whatnext-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mark Norman Francis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whatnext-0.0.1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: whatnext
+Version: 0.0.1
+Summary: A lister of tasks found in Markdown files
+Author: Mark Norman Francis
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/norm/whatnext
+Project-URL: Repository, https://github.com/norm/whatnext
+Project-URL: Documentation, https://github.com/norm/whatnext
+Keywords: cli,markdown,tasks,todo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+License-File: LICENSE
+Requires-Dist: toml
+Provides-Extra: test
+Requires-Dist: flake8; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# What next?
+
+Document your tasks in Markdown files, using ["standard"][sn] notation:
+
+```markdown
+- [ ] empty, this task is outstanding
+- [X] crossed, this task has been completed
+```
+
+Then install `whatnext`:
+
+```bash
+pip install whatnext
+```
+
+Now run it and it'll tell you what's next:
+
+```bash
+(computer)% whatnext
+README.md:
+    # What next?
+    - [ ] empty, this task is outstanding
+```
+
+More detail to be found:
+
+- [The basics of task formatting](docs/basics.md)
+- [whatnext usage and arguments](docs/usage.md)
+- [The `.whatnext` file](docs/dotwhatnext.md)
+
+
+## The reason
+
+I like to keep tasks in Markdown files. That way they can be interspersed
+within instructions, serving as reminders, FIXMEs, and other todos.
+
+
+[sn]: https://blog.github.com/2013-01-09-task-lists-in-gfm-issues-pulls-comments/

whatnext-0.0.1/README.md

@@ -0,0 +1,38 @@
+# What next?
+
+Document your tasks in Markdown files, using ["standard"][sn] notation:
+
+```markdown
+- [ ] empty, this task is outstanding
+- [X] crossed, this task has been completed
+```
+
+Then install `whatnext`:
+
+```bash
+pip install whatnext
+```
+
+Now run it and it'll tell you what's next:
+
+```bash
+(computer)% whatnext
+README.md:
+    # What next?
+    - [ ] empty, this task is outstanding
+```
+
+More detail to be found:
+
+- [The basics of task formatting](docs/basics.md)
+- [whatnext usage and arguments](docs/usage.md)
+- [The `.whatnext` file](docs/dotwhatnext.md)
+
+
+## The reason
+
+I like to keep tasks in Markdown files. That way they can be interspersed
+within instructions, serving as reminders, FIXMEs, and other todos.
+
+
+[sn]: https://blog.github.com/2013-01-09-task-lists-in-gfm-issues-pulls-comments/

whatnext-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "whatnext"
+version = "0.0.1"
+description = "A lister of tasks found in Markdown files"
+readme = "README.md"
+authors = [{ name = "Mark Norman Francis"}]
+license = "MIT"
+requires-python = ">=3.10"
+keywords = [
+    "cli",
+    "markdown",
+    "tasks",
+    "todo",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "toml",
+]
+
+[project.urls]
+Homepage = "https://github.com/norm/whatnext"
+Repository = "https://github.com/norm/whatnext"
+Documentation = "https://github.com/norm/whatnext"
+
+[project.optional-dependencies]
+test = [
+    "flake8",
+    "pytest",
+]
+
+[project.scripts]
+whatnext = "whatnext.cli:main"
+
+[tool.setuptools]
+packages = ["whatnext"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

whatnext-0.0.1/setup.cfg

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

whatnext-0.0.1/tests/test_task.py

@@ -0,0 +1,44 @@
+from whatnext.models import Task, State
+
+
+class TestTask:
+    task = Task(
+        "# Indicating the state of a task / Multiline tasks and indentation",
+
+        "- [ ] Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
+        "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+
+        State.INCOMPLETE,
+    )
+
+    def test_wraps_at_40_chars(self):
+        assert self.task.wrapped_text(width=40) == [
+            "    - [ ] Lorem ipsum dolor sit amet,",
+            "          consectetur adipisicing elit,",
+            "          sed do eiusmod tempor",
+            "          incididunt ut labore et dolore",
+            "          magna aliqua.",
+        ]
+        assert self.task.wrapped_heading(width=40) == [
+            "    # Indicating the state of a task /",
+            "      Multiline tasks and indentation",
+        ]
+
+    def test_no_wrap_at_120_chars(self):
+        assert self.task.wrapped_text(width=120) == [
+            "    - [ ] Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
+            "sed do eiusmod tempor incididunt ut labore et dolore",
+            "          magna aliqua.",
+        ]
+        assert self.task.wrapped_heading(width=120) == [
+            "    # Indicating the state of a task / Multiline tasks and indentation"
+        ]
+
+    def test_default_width_80_chars(self):
+        assert self.task.wrapped_text() == [
+            "    - [ ] Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do",  # noqa: E501
+            "          eiusmod tempor incididunt ut labore et dolore magna aliqua.",
+        ]
+        assert self.task.wrapped_heading() == [
+            "    # Indicating the state of a task / Multiline tasks and indentation"
+        ]

whatnext-0.0.1/whatnext/cli.py

@@ -0,0 +1,193 @@
+import argparse
+import fnmatch
+import os
+import shutil
+import toml
+
+from whatnext.models import MarkdownFile
+
+
+def get_terminal_width():
+    columns_env = os.environ.get("COLUMNS")
+    if columns_env:
+        width = int(columns_env)
+    else:
+        width = shutil.get_terminal_size().columns
+    if width < 40:
+        width = 80
+    return width
+
+
+def load_config(config_path=None, directory="."):
+    if config_path is None:
+        config_path = os.path.join(directory, ".whatnext")
+    if os.path.exists(config_path):
+        with open(config_path) as handle:
+            return toml.load(handle)
+    return {}
+
+
+def is_ignored(filepath, ignore_patterns):
+    for pattern in ignore_patterns:
+        if fnmatch.fnmatch(filepath, pattern):
+            return True
+    return False
+
+
+def find_markdown_files(directory=".", ignore_patterns=None, include_all=False):
+    if ignore_patterns is None:
+        ignore_patterns = []
+    markdown_files = []
+    for root, dirs, files in os.walk(directory):
+        for filename in files:
+            if filename.endswith(".md"):
+                filepath = os.path.join(root, filename)
+                relative_path = os.path.relpath(filepath, directory)
+                if is_ignored(relative_path, ignore_patterns):
+                    continue
+                md_file = MarkdownFile(filepath, directory)
+                tasks = md_file.tasks if include_all else md_file.incomplete
+                if tasks:
+                    markdown_files.append(md_file)
+
+    # files are examined depth-last as a lightweight prioritisation
+    return sorted(
+        markdown_files,
+        key=lambda file: (
+            file.display_path.count(os.sep),
+            file.display_path,
+        )
+    )
+
+
+def progress_bar(complete, total, width):
+    filled = round(width * complete / total) if total else 0
+    return "█" * filled + "░" * (width - filled)
+
+
+def format_summary(markdown_files, width):
+    widest = max(len(mf.tasks) for mf in markdown_files)
+    count_width = len(f"{widest}/{widest}")
+    gap = "  "
+    bar_width = (
+        width
+        - count_width
+        - max(len(mf.display_path) for mf in markdown_files)
+        - len(gap) * 3
+    )
+
+    lines = []
+    for md_file in markdown_files:
+        total = len(md_file.tasks)
+        complete = len(md_file.complete)
+        bar = progress_bar(
+            complete,
+            total,
+            round(bar_width * total / widest)
+        )
+
+        lines.append(
+            f"{bar.ljust(bar_width)}{gap}"
+            f"{f'{complete}/{total}'.rjust(count_width)}{gap}"
+            f"{md_file.display_path}"
+        )
+
+    return "\n".join(lines)
+
+
+def format_tasks(markdown_files, width, include_all):
+    lines = []
+    for md_file in markdown_files:
+        tasks = md_file.tasks if include_all else md_file.incomplete
+        lines.append(f"{md_file.display_path}:")
+        current_heading = None
+        for task in tasks:
+            if task.heading and task.heading != current_heading:
+                lines.extend(task.wrapped_heading(width))
+                current_heading = task.heading
+            lines.extend(task.wrapped_text(width))
+    return "\n".join(lines)
+
+
+class CapitalisedHelpFormatter(argparse.RawDescriptionHelpFormatter):
+    def add_usage(self, usage, actions, groups, prefix=None):
+        if prefix is None:
+            prefix = "Usage: "
+        super().add_usage(usage, actions, groups, prefix)
+
+    def start_section(self, heading):
+        super().start_section(heading.capitalize() if heading else heading)
+
+
+class ShortHelpAction(argparse.Action):
+    def __init__(self, option_strings, dest, **kwargs):
+        super().__init__(option_strings, dest, nargs=0, **kwargs)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        print(parser.format_usage().rstrip())
+        parser.exit()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="List tasks found in Markdown files",
+        epilog="""\
+Task States:
+  - [ ]     Not started (shown by default)
+  - [X]     Done (hidden by default, use --all)
+""",
+        add_help=False,
+        formatter_class=CapitalisedHelpFormatter,
+    )
+    parser.add_argument(
+        "-h",
+        action=ShortHelpAction,
+        help="Show the usage reminder and exit",
+    )
+    parser.add_argument(
+        "--help",
+        action="help",
+        help="Show this help message and exit",
+    )
+    parser.add_argument(
+        "--dir",
+        default=".",
+        help="Directory to search (default: current directory)",
+    )
+    parser.add_argument(
+        "-s", "--summary",
+        action="store_true",
+        help="Show summary of task counts per file",
+    )
+    parser.add_argument(
+        "-a", "--all",
+        action="store_true",
+        help="Include all tasks and files, not just incomplete",
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to config file (default: .whatnext in search directory)",
+    )
+    parser.add_argument(
+        "--ignore",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help="Ignore files matching pattern (can be specified multiple times)",
+    )
+    args = parser.parse_args()
+
+    config_path = args.config or os.environ.get("WHATNEXT_CONFIG")
+    config = load_config(config_path, args.dir)
+    ignore_patterns = config.get("ignore", []) + args.ignore
+    markdown_files = find_markdown_files(args.dir, ignore_patterns, args.all)
+
+    if not markdown_files:
+        return
+
+    width = get_terminal_width()
+
+    if args.summary:
+        print(format_summary(markdown_files, width))
+    else:
+        print(format_tasks(markdown_files, width, args.all))

whatnext-0.0.1/whatnext/models.py

@@ -0,0 +1,150 @@
+from enum import Enum
+import os
+import re
+import textwrap
+
+
+class State(Enum):
+    def __new__(cls, value, markers):
+        obj = object.__new__(cls)
+        obj._value_ = value
+        obj.markers = markers
+        return obj
+
+    INCOMPLETE = ("incomplete", [" "])
+    COMPLETE = ("complete", ["X", "x"])
+
+    @classmethod
+    def all_markers(cls):
+        markers = []
+        for state in cls:
+            markers.extend(state.markers)
+        return markers
+
+    @classmethod
+    def from_marker(cls, marker):
+        for state in cls:
+            if marker in state.markers:
+                return state
+        raise ValueError(f"Unknown marker: {marker}")
+
+
+class Task:
+    def __init__(self, heading, text, state):
+        self.heading = heading
+        self.text = text
+        self.state = state
+
+    def wrapped_text(self, width=80, indent="    "):
+        text = " ".join(self.text.split())
+        if width is None or len(indent + text) <= width:
+            return [indent + text]
+        return textwrap.wrap(
+            text,
+            width=width,
+            initial_indent=indent,
+            subsequent_indent=indent + "      ",
+        )
+
+    def wrapped_heading(self, width=80, indent="    "):
+        if not self.heading:
+            return []
+        if width is None or len(indent + self.heading) <= width:
+            return [indent + self.heading]
+        return textwrap.wrap(
+            self.heading,
+            width=width,
+            initial_indent=indent,
+            subsequent_indent=indent + "  ",
+        )
+
+
+class MarkdownFile:
+    HEADING_PATTERN = re.compile(r"""
+        ^
+            (\#+) \s+ (.*)
+        $
+    """, re.VERBOSE)
+
+    VALID_STATES = re.escape("".join(State.all_markers()))
+    TASK_PATTERN = re.compile(rf"""
+        ^
+            (\s*)
+            -[ ]
+            \[ ([{VALID_STATES}]) \]
+    """, re.VERBOSE)
+
+    def __init__(self, path, base_dir="."):
+        self.path = path
+        self.base_dir = base_dir
+        self.tasks = self.extract_tasks()
+
+    def extract_tasks(self):
+        tasks = []
+        for heading, lines in self.sections():
+            tasks.extend(self.tasks_in_section(heading, lines))
+        return tasks
+
+    def sections(self):
+        heading = None
+        lines = []
+        results = []
+
+        # stack stores (level, text) -- explicit level needed for
+        # skipped headings (# -> ### -> ##, where position != depth)
+        stack = []
+
+        with open(self.path) as handle:
+            for line in handle:
+                line = line.rstrip("\n")
+                if match := self.HEADING_PATTERN.match(line):
+                    if lines:
+                        results.append((heading, lines))
+                        lines = []
+                    level = len(match.group(1))
+                    while stack and stack[-1][0] >= level:
+                        stack.pop()
+                    stack.append((level, match.group(2)))
+                    heading = "# " + " / ".join(text for _, text in stack)
+                else:
+                    lines.append(line)
+
+            if lines:
+                results.append((heading, lines))
+
+        return results
+
+    def tasks_in_section(self, heading, lines):
+        tasks = []
+        index = -1
+        while (index := index + 1) < len(lines):
+            if match := self.TASK_PATTERN.match(lines[index]):
+                text = lines[index].lstrip()
+                indent = len(match.group(1)) + 6
+                while (
+                    index + 1 < len(lines)
+                    and self.is_continuation(lines[index + 1], indent)
+                ):
+                    index += 1
+                    text += "\n" + lines[index].strip()
+                tasks.append(Task(heading, text, State.from_marker(match.group(2))))
+
+        return tasks
+
+    def is_continuation(self, line, indent):
+        if not line.strip():
+            return False
+        leading = len(line) - len(line.lstrip())
+        return leading == indent
+
+    @property
+    def display_path(self):
+        return os.path.relpath(self.path, self.base_dir)
+
+    @property
+    def complete(self):
+        return [task for task in self.tasks if task.state == State.COMPLETE]
+
+    @property
+    def incomplete(self):
+        return [task for task in self.tasks if task.state == State.INCOMPLETE]

whatnext-0.0.1/whatnext.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: whatnext
+Version: 0.0.1
+Summary: A lister of tasks found in Markdown files
+Author: Mark Norman Francis
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/norm/whatnext
+Project-URL: Repository, https://github.com/norm/whatnext
+Project-URL: Documentation, https://github.com/norm/whatnext
+Keywords: cli,markdown,tasks,todo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+License-File: LICENSE
+Requires-Dist: toml
+Provides-Extra: test
+Requires-Dist: flake8; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# What next?
+
+Document your tasks in Markdown files, using ["standard"][sn] notation:
+
+```markdown
+- [ ] empty, this task is outstanding
+- [X] crossed, this task has been completed
+```
+
+Then install `whatnext`:
+
+```bash
+pip install whatnext
+```
+
+Now run it and it'll tell you what's next:
+
+```bash
+(computer)% whatnext
+README.md:
+    # What next?
+    - [ ] empty, this task is outstanding
+```
+
+More detail to be found:
+
+- [The basics of task formatting](docs/basics.md)
+- [whatnext usage and arguments](docs/usage.md)
+- [The `.whatnext` file](docs/dotwhatnext.md)
+
+
+## The reason
+
+I like to keep tasks in Markdown files. That way they can be interspersed
+within instructions, serving as reminders, FIXMEs, and other todos.
+
+
+[sn]: https://blog.github.com/2013-01-09-task-lists-in-gfm-issues-pulls-comments/

whatnext-0.0.1/whatnext.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENCE
+LICENSE
+README.md
+pyproject.toml
+tests/test_task.py
+whatnext/__init__.py
+whatnext/cli.py
+whatnext/models.py
+whatnext.egg-info/PKG-INFO
+whatnext.egg-info/SOURCES.txt
+whatnext.egg-info/dependency_links.txt
+whatnext.egg-info/entry_points.txt
+whatnext.egg-info/requires.txt
+whatnext.egg-info/top_level.txt

whatnext-0.0.1/whatnext.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

whatnext-0.0.1/whatnext.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+whatnext = whatnext.cli:main

whatnext-0.0.1/whatnext.egg-info/requires.txt

@@ -0,0 +1,5 @@
+toml
+
+[test]
+flake8
+pytest

whatnext-0.0.1/whatnext.egg-info/top_level.txt

@@ -0,0 +1 @@
+whatnext