#MAgenda

magenda.py is a Python 3 script for creating an agenda of task-list items in GitHub Flavored Markdown files.

The script is released 'as is' with no warranty under the GNU General Public License, version 2.0.

#Requirements

It requires the following Python 3 package:

• blessings

On Debian-based systems, the prerequisite can be installed as follows:

sudo apt-get install python3-blessings

#Data format

A task-list item is a list item with a task-list item marker after the list marker. [ ] marks uncompleted tasks, [/] ongoing tasks, and [x] or [X] completed tasks.

In addition to task-list item markers, this script also recognises Obisdian Dataview fields in the first line of a task-list item. For this line, the following general format is assumed:

<indentation>? <list marker> <task-list item marker> <title> <field>*

A <field> has the form [<key>:: <value>]. [due:: YYYY-MM-DD] represents the task’s due date, and [done:: YYYY-MM-DD] or [completion:: YYYY-MM-DD] its completion date. <field>s with other keys may precede <field>s representing the due date or the completion date.

Indented task-list items are taken to be subtasks, for example:

- [/] buy presents: [for:: ABC]
  - [x] buy birthday present [due:: 2023-12-18] [done:: 2023-12-16]
  - [ ] buy Christmas present: [with:: XYZ] [due:: 2023-12-24]
    from ABC’s wish list

#Usage

The script is to be used as follows:

usage: magenda.py [-h] [-c] [-C] [-d num] [-n] [-r] [-s] [-u] [-v] file [file ...]

positional arguments:
  file                  Markdown file

optional arguments:
  -h, --help            show this help message and exit
  -c, --completed-tasks show completed tasks
  -C, --force-color     preserve color and formatting when piping output
  -d num, --days num    restrict number of days
  -n, --line-number     output line number
  -r, --reversed        reverse sort order
  -s, --subtasks        include subtasks
  -u, --undated-tasks   include undated tasks
  -v, --version         show program's version number and exit

Running the script with options -s and -u on a Markdown file.md containing the task-list items above will generate the following output:

Sun, 24 Dec 2023
file.md:buy Christmas present with:XYZ
Undated
file.md:buy presents for:ABC

Given these options, subtasks and undated tasks are considered in addition to dated tasks.

By default, uncompleted and ongoing tasks are taken into account. With option -c, completed tasks are listed instead. Thus, running the script with options -c and -s on file.md outputs:

Sat, 16 Dec 2023
file.md:buy birthday present

In order to restrict the date range, use option -d with the number of days from today as an argument. Option -r reverses the date order. Line numbers can be output in addition to file names by means of option -n.

In a terminal, the output is pretty-printed. Option -C preserves colors and formatting codes when piping the output through GNU less or similar programs.

Andreas Nolda (andreas@nolda.org)